Skip to main content
Use POST /agui to connect an AG-UI client to a running Harnest agent. The endpoint uses the same agent and runtime policy as /responses.

​
Send your first turn

1

Start your agent

From your agent folder:
The default local address is http://127.0.0.1:1907.
2

Send an AG-UI request

In another terminal, send a user message. -N lets curl display events as they arrive.
These commands assume a local agent without authentication. For a protected deployment, send the authentication configured by its owner. For bearer authentication, add -H "Authorization: Bearer $HARNEST_TOKEN".
3

Continue the conversation

Keep the same threadId, choose a new runId, and end messages with the next user message. Harnest uses that message’s text and retains the server-side conversation. A client can keep its message history in the request for UI snapshots.

​
Thread and run identity

Message content can be a text string or an array of text parts. Media parts are rejected. A tool result or approval response resumes an interaction instead of starting a new user turn; see Handle interactions.

​
Read completion and failure

Text and tool activity arrive as AG-UI events. Structured final output is included in RUN_FINISHED.result. A finished transport run can also hand control to the UI or report an external wait, so inspect its outcome before treating the agent’s work as complete. Invalid request envelopes fail before streaming. Execution failures emit RUN_ERROR. Use the run’s error to show failure in the UI and allow the user to start another turn when no interaction is pending.

​
Cancel a run

Abort or close the active HTTP request. Harnest cancels the managed response and awaits cleanup. Cancellation is cooperative and does not undo tool or external side effects that already completed.

​
Configure the endpoint

Authentication, ownership, limits, timeouts, and concurrency follow the server configuration. Do not use message content, state, or forwardedProps as authentication. When embedding create_neutral_app or create_neutral_router, set agui_enabled=False to disable the AG-UI route.