Skip to content
oHallo Developers

Agents

Agents are AI workers that perform specific tasks in the conversation pipeline. System agents handle core pipeline steps (orchestration, message composition, reply validation, learning extraction). Custom agents handle domain-specific tasks — you create them, bind them to MCP server connections, and give them instructions.

List all agents

Section titled “List all agents”

Retrieve all agent definitions for your account, including both system and custom agents.

Required scope: agents:read

Terminal window
curl "https://api.ohallo.eu/api/agent-definitions" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "items": [
    {
      "id": "00000001-0000-4000-8000-000000000001",
      "name": "Conversation Orchestrator",
      "description": "Analyses customer messages, dispatches specialist agents, evaluates results",
      "agentRole": "system",
      "model": "claude-sonnet-4-6",
      "customInstructions": null,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    },
    {
      "id": "abcdef12-3456-4890-abcd-ef1234567890",
      "name": "Order Lookup Agent",
      "description": "Retrieves order details, tracking information, and delivery status from the order management system",
      "agentRole": "specialist",
      "model": "claude-sonnet-4-6",
      "customInstructions": "When looking up orders, always include the expected delivery date and current tracking status.",
      "createdAt": "2026-02-01T10:00:00.000Z",
      "updatedAt": "2026-03-10T14:00:00.000Z"
    }
  ],
  "total": 6
}

List custom agents

Section titled “List custom agents”

Retrieve only the custom (admin-defined) specialist agents.

Required scope: agents:read

Terminal window
curl "https://api.ohallo.eu/api/agent-definitions/custom" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Create custom agent

Section titled “Create custom agent”

Create a new specialist agent and bind it to one or more MCP server connections.

Required scope: agents:write

Terminal window
curl -X POST "https://api.ohallo.eu/api/agent-definitions/custom" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Returns Agent",
    "description": "Handles return requests, checks eligibility, and initiates return labels",
    "instructions": "You handle product return requests. Always verify the order number and check that the item is within the return window (30 days from delivery). If eligible, use the create_return tool to initiate the return and provide the customer with a return label.",
    "mcpConnectionIds": ["11111111-2222-4788-9444-555555555555"]
  }'

Request body:

FieldTypeRequiredDescription
namestringYesDisplay name for the agent
descriptionstringYesWhat this agent does — the Orchestrator reads this to decide when to dispatch it
instructionsstringYesBase prompt and behavioural instructions
modelstringNoLLM model to use (defaults to claude-sonnet-4-6)
mcpConnectionIdsUUID[]YesMCP connections this agent can call tools on (at least one)

Response:

{
  "id": "99887766-5544-4322-9100-ffeeddccbbaa",
  "name": "Returns Agent",
  "description": "Handles return requests, checks eligibility, and initiates return labels",
  "agentRole": "specialist",
  "model": "claude-sonnet-4-6",
  "customInstructions": "You handle product return requests. Always verify the order number and check that the item is within the return window (30 days from delivery). If eligible, use the create_return tool to initiate the return and provide the customer with a return label.",
  "createdAt": "2026-03-15T16:00:00.000Z",
  "updatedAt": "2026-03-15T16:00:00.000Z"
}

The description field is critical. The Orchestrator reads agent descriptions to decide which agents to dispatch for each conversation turn. Write a clear, specific description of what the agent handles.

Update custom agent

Section titled “Update custom agent”

Update a custom agent’s configuration. Only the fields you include are changed.

Required scope: agents:write

Terminal window
curl -X PATCH "https://api.ohallo.eu/api/agent-definitions/custom/99887766-5544-4322-9100-ffeeddccbbaa" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You handle product return requests. Always verify the order number and check that the item is within the return window (30 days from delivery, or 60 days for premium account customers). If eligible, use the create_return tool to initiate the return and provide the customer with a return label. If the item is damaged, request a photo before processing."
  }'

Response: Returns the full updated agent definition.

Delete custom agent

Section titled “Delete custom agent”

Delete a custom agent. System agents cannot be deleted.

Required scope: agents:write

Terminal window
curl -X DELETE "https://api.ohallo.eu/api/agent-definitions/custom/99887766-5544-4322-9100-ffeeddccbbaa" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Update system agent instructions

Section titled “Update system agent instructions”

You cannot modify system agents, but you can add custom instructions that supplement their default behaviour. This endpoint updates a single agent’s instruction override (PATCH /agent-definitions/:id/instructions).

Required scope: agents:write

Terminal window
curl -X PATCH "https://api.ohallo.eu/api/agent-definitions/00000001-0000-4000-8000-000000000001/instructions" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "customInstructions": "When classifying intents, always check for order-related queries first. Our customers most frequently ask about order status and delivery times."
  }'

Response: Returns the updated agent definition.

Agent executions

Section titled “Agent executions”

View the execution history for agents on a specific conversation. This is useful for debugging and understanding how the AI processed a conversation.

Required scope: conversations:read

Terminal window
curl "https://api.ohallo.eu/api/agent-executions?conversationId=c9f8e7d6-b5a4-3210-fedc-ba9876543210" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "items": [
    {
      "id": "aaa11111-bbb2-4ccc3-9ddd4-eee555555555",
      "agentDefinitionId": "00000001-0000-4000-8000-000000000001",
      "agentName": "Conversation Orchestrator",
      "conversationId": "c9f8e7d6-b5a4-3210-fedc-ba9876543210",
      "status": "completed",
      "toolCallCount": 0,
      "durationMs": 2340,
      "createdAt": "2026-03-15T09:12:05.000Z"
    },
    {
      "id": "fff66666-7777-4888-9999-aaa000000000",
      "agentDefinitionId": "abcdef12-3456-4890-abcd-ef1234567890",
      "agentName": "Order Lookup Agent",
      "conversationId": "c9f8e7d6-b5a4-3210-fedc-ba9876543210",
      "status": "completed",
      "toolCallCount": 2,
      "durationMs": 4120,
      "createdAt": "2026-03-15T09:12:08.000Z"
    }
  ],
  "total": 4
}

Tool calls

Section titled “Tool calls”

View the individual MCP tool calls made during an agent execution.

Required scope: conversations:read

Terminal window
curl "https://api.ohallo.eu/api/tool-calls?executionId=exec_fff66666-ggg7-hhh8-iii9-jjj000000000" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "items": [
    {
      "id": "11112222-3333-4788-9555-666677778888",
      "executionId": "fff66666-7777-4888-9999-aaa000000000",
      "toolName": "get_order",
      "input": {
        "orderNumber": "NP-2026-0142"
      },
      "output": {
        "orderId": "ord_998877",
        "status": "processing",
        "expectedDelivery": "2026-03-20",
        "items": [
          { "sku": "BRG-4420", "name": "Precision Bearing 4420", "quantity": 50 }
        ]
      },
      "success": true,
      "durationMs": 890,
      "createdAt": "2026-03-15T09:12:09.000Z"
    },
    {
      "id": "99998888-7777-4788-9555-444433332222",
      "executionId": "fff66666-7777-4888-9999-aaa000000000",
      "toolName": "track_shipment",
      "input": {
        "orderId": "ord_998877"
      },
      "output": {
        "carrier": "PostNord",
        "trackingNumber": "PN-DK-2026-88776655",
        "status": "label_created",
        "estimatedDelivery": "2026-03-20"
      },
      "success": true,
      "durationMs": 1240,
      "createdAt": "2026-03-15T09:12:10.000Z"
    }
  ],
  "total": 2
}

How agents work together

Section titled “How agents work together”

When a customer message arrives, the agent pipeline executes in sequence:

  1. Orchestrator — Analyses the message, classifies the intent, and decides which specialist agents to dispatch. It reads the description field of every available agent to make this decision. The Orchestrator runs in a loop, dispatching agents and evaluating their results until it determines enough information has been gathered.

  2. Specialist Agents — Execute in the order determined by the Orchestrator. Each agent calls tools on its bound MCP connections to gather data or perform actions.

  3. Message Agent — Receives the combined results from all specialist agents and composes the final reply.

  4. Validation Agent — Checks the drafted reply for factual accuracy and policy compliance before delivery.

Custom agents participate in step 2. The better your agent’s description matches the customer’s intent, the more reliably the Orchestrator will dispatch it.

Looking for the product? Visit ohallo.eu  ·  Help Centre  ·  Contact

Copyright 2026 oHallo ApS. All rights reserved.