Tools and interactions

Agents can use harness built-ins, connected applications, code tools, client tools, referenced workflows, MCP tools, and platform tools injected by Agenta.

Tool types

Type	Execution location
Harness built-in	Harness and sandbox; do not list in tools
gateway_connection	Connected application through the gateway
code	Runner-provided Python or Node runtime
client	Your application
reference	Another Agenta workflow, server-side
MCP	Configured HTTP MCP server

A connected application is one gateway_connection entry for the whole integration. The older per-action gateway shape is legacy.

Client tools

{
  "type": "client",
  "name": "lookup_account",
  "description": "Find an account by email.",
  "input_schema": {
    "type": "object",
    "properties": { "email": { "type": "string" } },
    "required": ["email"]
  },
  "permission": "allow"
}

When called, the turn pauses with a client_tool interaction. Post the result to POST /api/sessions/interactions/{interaction_id}/respond with an Idempotency-Key header. A request without the header returns 422.

curl -X POST \
  "https://eu.cloud.agenta.ai/api/sessions/interactions/019d952f-0000-0000-0000-000000000002/respond" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: call_019d952f" \
  -d '{
    "answer": {
      "tool_call_id": "call_019d952f",
      "outcome": "completed",
      "output": { "account_id": "acct_4821", "name": "Example Company" }
    }
  }'

The endpoint answers 202 Accepted. The run continues once every pending interaction of the paused execution has an answer. A retry with the same key and the same answer is safe: it does not answer twice, and it returns 202 with the current state. The full request and response shape is in Invoke an agent.

Use outcome: "error" and an error output when the client action fails.

Permission resolution

1. A code, client, or reference tool's permission wins.
2. A connected app uses policy.permissions.tools[tool_key], then its connection default.
3. inherit uses runner.permissions.default.
4. allow_reads allows read-hinted tools and asks for the rest.

The final result is allow, ask, or deny. ask creates a user_approval interaction; deny returns a tool error. Pi built-ins also use harness.permissions rules.

After a disconnect, query interactions by session and answer only records still marked pending.