Agents

Hyphen agents are operational decision-makers. They reason step-by-step, use tools, observe results, and iterate toward an objective. They are not chatbots. They process, investigate, classify, recommend, and act — with every thought and action captured in a reasoning trace.

The key constraint: agents operate inside a cage defined by the workflow spec. They can only use tools you've explicitly declared. They can't discover or invent capabilities. If the spec says they can look up tickets and send emails, that's all they can do — even if the LLM is capable of much more.

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 via the agent API, outside any workflow. Use for ad-hoc tasks, agent-as-trigger, and orchestrator patterns.

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 full reasoning trace (?include_trace=true). :::

GET/agents/:id/trace

Get the complete reasoning 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__`, `__run_workflow__`, `__pause_for_human__`, memory, logging
Tool Declarations	Typed tool declarations — 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
Deployment Patterns	Three patterns: agent as step, trigger, or orchestrator