Long-running tools

Start asynchronous application-owned work and return its final result to an agent session.

Custom tools execute in your application. For work that cannot finish while the agent is waiting, return a running result promptly, continue the external job, then send a final result when it finishes.

This keeps tool calling from blocking the chat for the full lifetime of an external job. The kickoff releases the pending tool call so the agent can respond and the conversation can continue while your application finishes the work in the background.

How the flow works

1. The stream emits agent.custom_tool_use.
2. Your application starts the external workflow.
3. Within five minutes, post user.custom_tool_result with status: "running".
4. That kickoff resolves the blocked custom tool call and lets the current agent turn continue.
5. When the external workflow finishes, post a second result with status: "completed" or "failed".
6. Herm updates the original running result, emits session.tool_updated, and starts a new agent turn with the final text.

If another turn is running, Herm queues the final result and starts its continuation automatically when the session becomes idle.

Start the workflow

The pending tool call allows approximately five minutes for a response. Send the kickoff well before that deadline:

curl -X POST "https://api.herm.run/v1/sessions/session_123/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "events": [
      {
        "type": "user.custom_tool_result",
        "tool_use_id": "custom_toolu_123",
        "content": [
          { "type": "text", "text": "Render job started. I will report when it finishes." }
        ],
        "status": "running",
        "is_error": false
      }
    ]
  }'

status: "running" is not a progress-only event. It is the response to the pending tool call, so the original agent turn resumes immediately with the kickoff text as tool output. Herm does not poll or supervise the external job.

Store the sessionId, tool_use_id, and the accepted result event id with your job record.

Complete the workflow

When the workflow finishes, send the final result with the same tool_use_id:

curl -X POST "https://api.herm.run/v1/sessions/session_123/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "events": [
      {
        "type": "user.custom_tool_result",
        "tool_use_id": "custom_toolu_123",
        "content": [
          { "type": "text", "text": "Render completed. The video is available at https://example.com/render/123." }
        ],
        "status": "completed",
        "is_error": false
      }
    ]
  }'

For failures, use status: "failed", set is_error: true, and include enough context in content for the model to respond appropriately.

When a matching running result exists, the completion replaces that result in event history. Its text is submitted to the agent as a new prompt, which starts a separate turn. Without a matching running result, the final result is appended as a new event and still starts a turn.

Update live tool UI

Live streams receive an ephemeral session.tool_updated event:

event: session.tool_updated
data: {"type":"session.tool_updated","payload":{"type":"session.tool_updated","tool_use_id":"custom_toolu_123","event_id":"evt_running_result","payload":{"type":"user.custom_tool_result","tool_use_id":"custom_toolu_123","content":[{"type":"text","text":"Render completed."}],"status":"completed","is_error":false}},...}

Patch the existing event identified by payload.event_id with payload.payload. The patch event itself is not retained. The client posting the completion should also apply the updated event returned in the 202 response in case its stream misses the ephemeral patch.

Retry safety

Final-result submissions are idempotent by session and tool_use_id. A retry returns the existing result instead of starting another continuation.

An immediate or running result can return 410 response_expired with "retryable": false if the session stopped waiting for it. Do not retry that response: Hermes has discarded the original pending tool call, so it can no longer be delivered. Send a new user message if you want the agent to try the action again.

Permission policies

Custom tools use the same always_allow, always_ask, and always_deny permission policies as other tools. With always_ask, handle the preceding agent.approval_request before expecting agent.custom_tool_use. Your application remains responsible for authorization, input validation, retries, idempotency, and side-effect safety.