Agents

An agent is a model, a system prompt and a list of tools. Each turn the model either calls tools — DirectOS runs them and feeds the results back — or gives its final answer. A tool that fails comes back to the model as an error it can react to, rather than killing the run.

• Tools are nodes. An agent’s tools are built-in node type ids — http.request, rag.query, memory.recall, postgres.query… GET /agents/tools lists what is allowed (triggers and the run-control nodes are not).
• Reflection. With reflect: true the agent spends one extra turn checking its own answer before finishing.
• Bounded. maxSteps (up to 50) caps the loop; a run that doesn’t converge fails with a clear error instead of looping forever.

• Delegation — every agent can hand a task to another agent and get its final answer back (delegate_to_agent), up to five levels deep. Each delegated run is recorded, so the whole tree shows up in the run history.
• Messaging — agents can leave each other asynchronous messages (message_agent). Unread messages are added to the recipient’s context at the start of its next run. People and other systems can leave messages too, with POST /agents/:id/messages.

curl -X POST https://api.directos.dev/api/agents \
  -H "authorization: Bearer $DIRECTOS_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Support researcher",
    "model": "claude-sonnet-5",
    "systemPrompt": "Answer from the handbook. Cite the section you used.",
    "tools": ["rag.query", "http.request"],
    "reflect": true
  }'

curl -X POST https://api.directos.dev/api/agents/<agent-id>/run \
  -H "authorization: Bearer $DIRECTOS_KEY" \
  -H 'content-type: application/json' \
  -d '{"input": "What is our refund window for annual plans?"}'

The run call waits for the agent to finish and returns the final answer with every step it took. Past runs are at GET /agents/runs?agentId=.