Built-in Tools

Every agent has access to these built-in tools. Include them in your tools array by name.

Tool	Purpose
`__complete__`	Signal task completion with final answer
`__run_workflow__`	Trigger another Hyphen workflow
`__pause_for_human__`	Pause and request human input
`__store_memory__`	Save data for later retrieval within the session
`__retrieve_memory__`	Recall previously stored data
`__log_progress__`	Record milestones for observability

`complete`

Signal that the agent has finished its task and provide the final answer.

Parameters

Parameter	Type	Required	Description
`answer`	string	Yes	The final answer or result
`confidence`	number	No	Confidence score 0–1 (default: 1.0)
`summary`	string	No	Brief summary of work performed

Example

json

{
  "thought": "I've verified the receipt, checked policy compliance, and the expense is within limits. Ready to approve.",
  "action": "__complete__",
  "action_input": {
    "answer": "Approve. Expense of $847 for client dinner is within the $1,000 entertainment policy limit. Receipt verified, date matches credit card statement.",
    "confidence": 0.95,
    "summary": "Verified receipt authenticity, checked against entertainment policy, confirmed credit card match."
  }
}

Result

The agent loop terminates successfully. The answer, confidence, and summary are stored in context under the result_key configured on the loop.

json

{
  "@agentResult": {
    "answer": "Approve. Expense of $847...",
    "confidence": 0.95,
    "summary": "Verified receipt authenticity..."
  }
}

Always include __complete__ in your tools list. Without it, the agent has no way to finish and will exhaust max_iterations.

---

`__run_workflow__`

Trigger another Hyphen workflow from within the agent. The agent can dispatch sub-tasks to specialized workflows and use the results in its reasoning.

Parameters

Parameter	Type	Required	Description
`workflow_id`	string	No*	ID of the workflow to run
`workflow_name`	string	No*	Name of the workflow (alternative to ID)
`input`	object	Yes	Input payload for the workflow
`wait`	boolean	No	Wait for completion (default: `true`)
`timeout_ms`	number	No	Timeout in milliseconds (default: 60000)

*Either workflow_id or workflow_name is required.

Example

json

{
  "thought": "I need to run the sanctions screening workflow for this customer before proceeding with onboarding.",
  "action": "__run_workflow__",
  "action_input": {
    "workflow_name": "sanctions_screening",
    "input": {
      "customer_name": "Acme Corp",
      "country": "DE",
      "registration_number": "HRB 12345"
    },
    "wait": true,
    "timeout_ms": 120000
  }
}

Result

json

{
  "workflow_run_id": "run_xyz789",
  "workflow_id": "wf_abc123",
  "status": "completed",
  "result": {
    "screening_result": "clear",
    "matches_found": 0
  },
  "context": { }
}

The agent receives the workflow's output as an observation and can reason about it in the next iteration.

Async dispatch. Set wait: false to trigger a workflow without waiting. The agent gets back a workflow_run_id immediately and can check status later or move on.

`__pause_for_human__`

Pause the agent and request human input. The agent's state is checkpointed — when the human responds, the agent resumes from exactly where it left off.

Parameters

Parameter	Type	Required	Description
`question`	string	Yes	Question for the human reviewer
`options`	string[]	No	List of choices to present
`context_summary`	string	No	Summary of work done so far
`urgency`	string	No	`"low"`, `"medium"`, or `"high"`

Example

json

{
  "thought": "I found two matching customers. I can't determine which one is correct from the data alone — I need a human to decide.",
  "action": "__pause_for_human__",
  "action_input": {
    "question": "Two customers match 'John Smith'. Which should I use for this refund?",
    "options": [
      "John Smith (ID: C-001) — Premium, member since 2019, $45K lifetime value",
      "John Smith (ID: C-047) — Standard, member since 2023, $2K lifetime value"
    ],
    "context_summary": "Processing refund #RF-789 for order #12345. Amount: $234.00.",
    "urgency": "medium"
  }
}

What Happens

Agent state is persisted (checkpointed)
Agent status changes to paused
An approval-style request is created
Human reviews context and responds via POST /agents/:id/resume
Agent resumes with the human's response as the next observation

Resuming

bash

curl -X POST http://localhost:3009/agents/{agentRunId}/resume \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "human_input": "Use John Smith C-001, the premium customer.",
    "approved": true
  }'

The agent's next iteration sees the human's response as an observation and continues reasoning.

`__store_memory__`

Store a key-value pair for later retrieval within the same agent execution. Use this to save intermediate results, extracted data, or decisions that you'll need in a later iteration.

Parameters

Parameter	Type	Required	Description
`key`	string	Yes	Storage key
`value`	any	Yes	Value to store (string, number, object, array)
`ttl_seconds`	number	No	Time-to-live before automatic expiration

Example

json

{
  "thought": "I found the customer's account details. Let me save this for when I draft the email.",
  "action": "__store_memory__",
  "action_input": {
    "key": "customer_info",
    "value": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "tier": "premium",
      "account_age_years": 4
    }
  }
}

Result

json

{
  "stored": true,
  "key": "customer_info",
  "message": "Stored value under key \"customer_info\""
}

`__retrieve_memory__`

Retrieve a previously stored value by key.

Parameters

Parameter	Type	Required	Description
`key`	string	Yes	Storage key to retrieve

Example

json

{
  "thought": "Now I need the customer info I saved earlier to personalize this email.",
  "action": "__retrieve_memory__",
  "action_input": {
    "key": "customer_info"
  }
}

Result (found)

json

{
  "found": true,
  "key": "customer_info",
  "value": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "tier": "premium",
    "account_age_years": 4
  },
  "stored_at": "2026-02-01T10:30:00Z"
}

Result (not found)

json

{
  "found": false,
  "key": "unknown_key",
  "message": "No memory found for key \"unknown_key\""
}

Memory scope. __store_memory__ and __retrieve_memory__ are scoped to a single agent execution. Memory does not persist across separate agent runs. For persistent storage across runs, use Custom Tables.

---

`__log_progress__`

Record a progress milestone without affecting execution flow. Useful for observability — tracking where the agent is in a long-running task.

Parameters

Parameter	Type	Required	Description
`message`	string	Yes	Progress description
`milestone`	string	No	Named milestone identifier
`data`	object	No	Structured data associated with the milestone

Example

json

{
  "thought": "Research phase is done. I found 3 articles and 2 contacts. Moving to drafting.",
  "action": "__log_progress__",
  "action_input": {
    "message": "Research phase complete. Found 3 relevant articles and 2 key contacts.",
    "milestone": "research_complete",
    "data": {
      "articles_found": 3,
      "contacts_found": 2,
      "sources": ["TechCrunch", "Company Blog", "SEC Filing"]
    }
  }
}

Result

json

{
  "logged": true,
  "milestone": "research_complete",
  "message": "Progress logged"
}

Progress logs appear in the agent's reasoning trace and are queryable for monitoring dashboards.

→ Next: Tool Declarations