Built-in Tools

Every agent run receives these built-in tools automatically. Do not declare them in your tools array.

Tool Purpose
__complete__ Signal task completion with final answer
__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..."
  }
}

Legacy: __run_workflow__ (Deprecated)

For existing workflows only. New agent specs should declare workflows as typed tools:

json
{ "type": "workflow", "id": "wfl-123e4567-e89b-12d3-a456-426614174000" }

Hyphen resolves declared workflow tools automatically and exposes them to the agent by their workflow name. The legacy __run_workflow__ action remains available for backward compatibility, but new docs and new workflows should use typed workflow declarations instead.

__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

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

Resuming

bash
curl -X POST https://your-hyphen.example.com/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": "jane@acme.com",
      "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": "jane@acme.com",
    "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,
  "message": "Research phase complete. Found 3 relevant articles and 2 key contacts.",
  "timestamp": "2026-02-01T10:35:00Z"
}

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

ā†’ Next: Tool Declarations