Agents

Hyphen agents are operational decision-makers. They use tools, observe results, and iterate toward an objective. They are not chatbots. They process, investigate, classify, recommend, and act, with each tool call and its model-provided rationale captured in an execution trace.

The key constraint: agents operate inside a cage defined by the workflow spec. They can use only the tools you declare. If the spec gives an agent ticket lookup and email tools, those are the capabilities available during the run.

flowchart TD subgraph "The Agent Cage" O["Objective"] --> T["Think"] T --> A["Act (declared tools only)"] A --> Ob["Observe result"] Ob --> T Ob --> C["Complete"] end Spec["Workflow Spec"] -.->|defines tools,<br/>iterations, guardrails| O H["Human"] -.->|reviews when<br/>agent escalates| A

Two Ways to Run Agents

As a workflow step. The agent is one step inside a larger deterministic workflow. Use type: "loop" with mode: "react". See Loop primitive.

json

{
  "type": "loop",
  "properties": {
    "mode": "react",
    "objective": "Investigate this exception",
    "tools": [{ "type": "action", "name": "lookup_record" }],
    "max_iterations": 10
  }
}

As a standalone agent. Execute directly through the agent API. Use this for ad hoc tasks, agent-as-trigger patterns, and orchestrators.

bash

POST /agents/execute

:::api POST /agents/execute Execute a standalone agent. Supports sync (wait for result) and async (?async=true, poll for status) modes. :::

:::api GET /agents/:id/status Get agent run status, optionally with the recorded agent trace (?include_trace=true). :::

GET/agents/:id/trace

Get the complete recorded trace for an agent run.

POST/agents/:id/resume

Resume a paused agent with human input.

What's in This Section

Page	Description
ReAct Loop	The think → act → observe cycle, prompt construction, iteration lifecycle
Built-in Tools	`__complete__`, `__pause_for_human__`, memory, logging
Tool Declarations	Typed declarations for action tools, workflow tools, and legacy formats
Stuck Detection	Recovery strategies when agents loop without progress
Reasoning Traces	Audit trail format, querying, compliance, secret redaction
Context and Budgets	What the model sees each turn, how large data stays out of the prompt, what a run may spend
Deployment Patterns	Three patterns: agent as step, trigger, or orchestrator