Neutral API

Call your agent through the same HTTP API whether it uses ADK or LangGraph. The default address is http://127.0.0.1:1907.

Send your first request

From your agent folder, run harnest serve .. In another terminal:

curl --fail-with-body -sS http://127.0.0.1:1907/responses \
  -H 'Content-Type: application/json' \
  -d '{"input":"Hello! What can you help me with?"}'

Read outputText and keep sessionId for follow-up turns. A session is created automatically. Send input; model configuration belongs on the agent. See response request fields for session reuse, streaming, metadata, and typed input. Continue the conversation, replacing the placeholder with the returned ID:

curl --fail-with-body -sS http://127.0.0.1:1907/responses \
  -H 'Content-Type: application/json' \
  -d '{"input":"Tell me more.","sessionId":"REPLACE_WITH_RETURNED_SESSION_ID"}'

For streaming, -N disables curl’s output buffering:

curl --fail-with-body -sS -N http://127.0.0.1:1907/responses \
  -H 'Content-Type: application/json' \
  -d '{"input":"Hello!","stream":true}'

Inspect status, not just the HTTP status code. A response can be completed, in_progress, or requires_action; see response recovery and approvals and client tools.

These commands target a local agent without authentication. For a protected deployment, use the authentication configured by its owner; for bearer authentication, add -H "Authorization: Bearer $HARNEST_TOKEN". Do not put credentials in metadata.

Discover the API

curl --fail-with-body -sS http://127.0.0.1:1907/agent
curl --fail-with-body -sS http://127.0.0.1:1907/openapi.json
curl --fail-with-body -sS http://127.0.0.1:1907/openapi.yaml

Fetch /agent for enabled routes and schema resources. Resolve resource URIs against the server address. JSON and YAML describe the same API; check POST /responses and its input schema before generating requests for a typed agent. Startup prints Swagger and schema URLs. Save YAML with curl --fail-with-body -sS http://127.0.0.1:1907/openapi.yaml -o openapi.yaml. In Swagger UI, open Send a message to the agent → Try it out → Execute. Authentication still applies. Set server.openapi: false to hide documentation routes.

Endpoints

See the HTTP route reference for sessions, media, responses, discovery, and health endpoints. Availability depends on the deployed configuration.

AG-UI clients

Connect an agent-facing UI through POST /agui. Harnest supports streamed text, shared state, frontend tools, and human approval on ADK and LangGraph. See AG-UI for supported capabilities, client integration, and interaction contracts.

Try the CopilotKit demo

Run the CopilotKit example to test both frameworks with a local React UI, without a model API key.

A2A bindings

Declare an A2A HTTP+JSON or JSON-RPC interface in agent-card.yaml to mount it beside the neutral API. See Agent2Agent (A2A) for discovery, Tasks, streaming, and recovery.

Response modes

JSON
SSE
WebSocket

Send one request to POST /responses and receive one completed response.

Set "stream": true. The stream starts with response.created and ends with response.completed or error.Cancel by aborting or closing the HTTP request, such as with AbortController. SSE is server-to-client only, so it has no cancel frame or terminal acknowledgement after disconnection. Harnest cancels the managed response and awaits cleanup.

Set server.live: true in config.yaml, then connect to /live on the HTTP server’s host and port. Send a connect frame, wait for session.connected, then send response.create frames. See Enable WebSockets.Cancel the active response with its server-issued ID:

{"type":"response.cancel","responseId":"resp_..."}

Harnest waits for managed model and tool cleanup, then sends response.completed with status: "cancelled". Partial deltas are not reported as committed output, and the socket remains ready for another response.create.When Harnest sends approval.requested, answer on the same socket:

{"type":"approval.decision","responseId":"resp_...","approvalId":"approval_...","decision":"approve"}

Harnest sends approval.resolved before resumed output. The HTTP approval endpoint remains available for approval interfaces that do not own the socket.

Cancellation is cooperative. It does not undo tool or external side effects that already completed.

Response status and recovery

Harnest records the latest status for every neutral JSON, SSE, and WebSocket response. Use the server-issued response ID and the same session ID:

GET /responses/resp_...?sessionId=session_...

The authenticated user and session must both match the original invocation. Harnest returns 404 for a missing or mismatched scope so callers cannot probe another user’s response IDs. Ordinary receipts last for the serving process. A Harnest-owned checkpointer also preserves terminal responses across restarts; pending approvals and client tools remain process-local. Advanced mode keeps the same API where Harnest owns the neutral transport. Recovery is best effort when your application replaces the graph, checkpointer, transport, or tool wiring; Harnest leaves those user-owned boundaries alone. All modes use the same portable activity contract. JSON returns these items in output. SSE and WebSocket use the corresponding response.* frames. JSON, SSE, and WebSocket expose the same portable activity types. Output policy controls which optional events callers receive.

[
  {"type":"agent_activity","agent":"researcher","activity":"started"},
  {
    "type":"thinking",
    "agent":"researcher",
    "content":[{"type":"thinking_text","text":"Check the constraints"}]
  },
  {
    "type":"agent_metadata",
    "agent":"researcher",
    "framework":"langgraph",
    "model":"provider-model",
    "finishReason":"stop",
    "usage":{"inputTokens":42,"outputTokens":9,"totalTokens":51}
  }
]

{"type":"response.agent_activity","sequence":1,"responseId":"resp_123","sessionId":"session_123","agent":"researcher","activity":"started"}
{"type":"response.thinking.delta","sequence":2,"responseId":"resp_123","sessionId":"session_123","agent":"researcher","delta":"Check the constraints"}
{"type":"response.agent_metadata","sequence":3,"responseId":"resp_123","sessionId":"session_123","agent":"researcher","framework":"langgraph","model":"provider-model","finishReason":"stop","usage":{"inputTokens":42,"outputTokens":9,"totalTokens":51}}

Optional reasoning, decision, and metadata events follow Output policy. See activity payloads for fields and transport encoding. By default Harnest omits native metadata fields. Configure OutputPolicy(agent_metadata=AgentMetadataMode.RAW) to add a raw mapping to each metadata event. See Output policy for the ADK and LangGraph namespaces and the disclosure warning. Checkpointed completion output includes normalized metadata. Raw metadata persists only with the explicit output-policy opt-in. Native metadata that you explicitly declare in a structured output remains namespaced under adk or langgraph. Treat that metadata as framework-specific rather than part of the portable activity contract. An external or queued durable wait returns status: in_progress. Poll the response ID with the same authenticated user and session until it is completed or failed. See Durable execution. Typed input, output, and media use the same contract in every mode. See Accept multimodal data.

Pagination properties

Follow nextCursor unchanged until it is null. Cursors are scoped to the user and, for transcripts, the session. See pagination limits. Malformed or cross-user cursors return 400.

Playground

The playground uses the neutral API for conversations and activity. Live is available only when the server advertises /live. Open /?session=<id> to restore an owned session. Enter its full ID if it is outside the session picker’s current page.

Auth path	Browser behavior
HTTP and SSE bearer token	Kept in page memory
Authenticated WebSocket	Requires a same-origin cookie

Browsers cannot add arbitrary authorization headers to a WebSocket handshake.

Overview

Get started

Harnest Studio

Guides

API reference

Send your first request

Discover the API

Endpoints

AG-UI clients

Try the CopilotKit demo

A2A bindings

Response modes

Response status and recovery

Playground

​Send your first request

​Discover the API

​Endpoints

​AG-UI clients

​Try the CopilotKit demo

​A2A bindings

​Response modes

​Response status and recovery

​Pagination properties

​Playground

Send your first request

Discover the API

Endpoints

AG-UI clients

Try the CopilotKit demo

A2A bindings

Response modes

Response status and recovery

Pagination properties

Playground