> ## Documentation Index > Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send a message to an agent > One turn: the agent reads `input` (and any `attachments`) and answers, using its tools, showing a form when it needs details, and running browser tasks (on the conversation’s cloud browser) or desktop tasks (on its linked computers) when it needs a website or a desktop app. Without `conversation_id` a new conversation starts. Waits up to 55 seconds; a turn still running then comes back `in_progress` (poll GET /v1/responses/{id}). With `stream: true` the answer is server-sent events: `response.created`; `output_text.delta` (`text`: the next piece of the reply as the model writes it; `output_text.reset` takes back what a failed try streamed); `message.delta` (each whole message once written); `tool_call.started`, `tool_call.completed` (a code run’s has `files`: what the code made); `ui` (a form: `surface_id`, `title`, `fields`, `a2ui`; the turn ends after it); `task.started` (`task_id`, `goal`, `kind`: `browser` or `desktop`, `computer` for a desktop task, `plan`: the steps the person sees as its progress, the browser’s `session_id`, and `live_url`: its live view in the console), `task.step` (`text`: what it says it's doing now, and with a plan `plan_step`: the step it's on), `task.completed`; `input.delivered` (messages sent meanwhile, read); with visual answers on, `answer.layout` first (its answer may be laid out as UI) and `message.view` (`seq`, `view`: that answer laid out as cards, before the reply ends; its text is still the answer); then `response.completed`, `response.failed`, `response.cancelled`, or `response.requires_action` (`response`: the reply, paused on a request in its `output`). A message sent while a reply is still running is queued for that reply instead: `202` at once (streamed or not), with the reply as it is now and `queued_message` (your message’s item, `queued: true`). The reply reads it at its next step, after the tool or task it’s running (a task it’s running reads it at its next step too), or carries on after its answer to answer it as well, so the one reply answers both: follow it on its own stream or with GET /v1/responses/{id}. Its stream has `input.delivered` (`seqs`: the items read, `to`: `reply` or `task`) when it reads them. A reply cancelled or failed before it read one leaves it in the conversation for the next turn. A failed turn still answers 200, with `status: failed`. If a deploy hands a streamed turn to another server, the stream can close without a `response.*` event: follow it with GET /v1/responses/{id}. A reply that reaches something needing approval (a procedure whose Approval is on, an HTTP tool with `approval: "always"`, or a step one of its tasks hands back: the task is `paused` until it’s decided, then carries on) pauses: `status: requires_action`, with the request (an `approval` item) in `output`. Decide it with `conversation_id` and `approval` (or an A2UI `action` on its surface), and no `input`; a question is answered the same way with `answer`. Your team decides, as the API key or the member signed in. The same reply carries on (same `id`), streamed with `stream: true`; it still waits while another request is open. With no paused reply (a task started directly) the answer is the decision: `{ object: "decision", approval | question }`. To decide without naming an agent (a task run without one) or streaming, use POST /v1/conversations/{conversation_id}/decisions. Someone deciding first: 409 with `code: already_decided` and `decided_by`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agents/{agent_id}/responses openapi: 3.1.0 info: title: Eager API version: 1.0.0 description: >- Train AI agents like new hires: hand an agent your files and coach it, and it writes its own procedures and works in any software, even without an API. Talk to your agents one message at a time (POST /v1/agents/{agent_id}/responses): they answer from their files, procedures and your HTTP tools, and run tasks on their own cloud browser or your linked computers when an answer needs a website or a desktop app. Manage agents (versioned: save a draft, publish it), their procedures, browser and computers; follow conversations and tasks, answer approvals, and fetch history and recordings. Run tasks yourself on a session: a customer’s computer through an invite link, or a cloud browser. Test agents with evals: chat, browser and desktop test cases, run several times against your agents and judged on the answer. Every change is in the org’s audit log. servers: - url: https://guidinghand.ai description: Production - url: https://dev.guidinghand.ai description: Development (Stripe test mode) security: - bearerAuth: [] tags: - name: Agents - name: Agent files - name: Agent tools - name: Agent folders - name: Computers description: >- Computers your org links with the Eager app, and pools of them, for agents’ desktop tasks. Attach them to an agent in its `resources.computers`. - name: Phone numbers description: >- Bring your own Twilio numbers: connect the account, add its numbers, and pick the agent that answers each. Calls are answered by the agent's published version. - name: Sessions - name: Tasks - name: Webhooks - name: Audit log - name: Test cases - name: Test sets - name: Test runs - name: Start states - name: Runners - name: Responses description: >- Talk to an agent: each call is one turn of a conversation. The agent answers with its files, procedures and tools (and, with Run code, its own sandbox), asks for details with forms, and runs browser and desktop tasks when an answer needs a website or a desktop app. - name: Conversations description: >- The history of each conversation: messages, tool calls and the tasks the agent started, in order. - name: Uploads description: >- Files for conversations: attach them to a message, and download what the agent’s code made. Kept as long as their conversation. - name: Procedures description: >- An agent’s playbooks: when to use each and its steps. The agent finds and follows them; ones it writes from a first run are marked written_by: agent. - name: Categories description: The kinds of request an org’s procedures and test cases are sorted into. - name: Escalations description: >- What needs your team: an approval only the team can give or a question only it can answer, in a real conversation; a procedure run that failed; and one that worked another way, with the procedure rewritten to match (a proposed change). Test chats never escalate; evals do, without webhooks. - name: Schedules description: >- Run an agent’s procedure on a cron expression, in a time zone, with the inputs it needs. Each run is a conversation of its own with nobody in it (`channel` `schedule` in its variables): the procedure’s steps without AI run outright when it has them, else the model follows it to its end. Its record says how it ended, what the agent said last and what it cost; the team hears by webhook (`schedule.run_completed`, `schedule.run_failed`), email and Slack or Teams, as the schedule says. paths: /v1/agents/{agent_id}/responses: parameters: - name: agent_id in: path required: true description: The agent’s id, e.g. `billing`. schema: type: string post: tags: - Responses summary: Send a message to an agent description: >- One turn: the agent reads `input` (and any `attachments`) and answers, using its tools, showing a form when it needs details, and running browser tasks (on the conversation’s cloud browser) or desktop tasks (on its linked computers) when it needs a website or a desktop app. Without `conversation_id` a new conversation starts. Waits up to 55 seconds; a turn still running then comes back `in_progress` (poll GET /v1/responses/{id}). With `stream: true` the answer is server-sent events: `response.created`; `output_text.delta` (`text`: the next piece of the reply as the model writes it; `output_text.reset` takes back what a failed try streamed); `message.delta` (each whole message once written); `tool_call.started`, `tool_call.completed` (a code run’s has `files`: what the code made); `ui` (a form: `surface_id`, `title`, `fields`, `a2ui`; the turn ends after it); `task.started` (`task_id`, `goal`, `kind`: `browser` or `desktop`, `computer` for a desktop task, `plan`: the steps the person sees as its progress, the browser’s `session_id`, and `live_url`: its live view in the console), `task.step` (`text`: what it says it's doing now, and with a plan `plan_step`: the step it's on), `task.completed`; `input.delivered` (messages sent meanwhile, read); with visual answers on, `answer.layout` first (its answer may be laid out as UI) and `message.view` (`seq`, `view`: that answer laid out as cards, before the reply ends; its text is still the answer); then `response.completed`, `response.failed`, `response.cancelled`, or `response.requires_action` (`response`: the reply, paused on a request in its `output`). A message sent while a reply is still running is queued for that reply instead: `202` at once (streamed or not), with the reply as it is now and `queued_message` (your message’s item, `queued: true`). The reply reads it at its next step, after the tool or task it’s running (a task it’s running reads it at its next step too), or carries on after its answer to answer it as well, so the one reply answers both: follow it on its own stream or with GET /v1/responses/{id}. Its stream has `input.delivered` (`seqs`: the items read, `to`: `reply` or `task`) when it reads them. A reply cancelled or failed before it read one leaves it in the conversation for the next turn. A failed turn still answers 200, with `status: failed`. If a deploy hands a streamed turn to another server, the stream can close without a `response.*` event: follow it with GET /v1/responses/{id}. A reply that reaches something needing approval (a procedure whose Approval is on, an HTTP tool with `approval: "always"`, or a step one of its tasks hands back: the task is `paused` until it’s decided, then carries on) pauses: `status: requires_action`, with the request (an `approval` item) in `output`. Decide it with `conversation_id` and `approval` (or an A2UI `action` on its surface), and no `input`; a question is answered the same way with `answer`. Your team decides, as the API key or the member signed in. The same reply carries on (same `id`), streamed with `stream: true`; it still waits while another request is open. With no paused reply (a task started directly) the answer is the decision: `{ object: "decision", approval | question }`. To decide without naming an agent (a task run without one) or streaming, use POST /v1/conversations/{conversation_id}/decisions. Someone deciding first: 409 with `code: already_decided` and `decided_by`. operationId: createResponse requestBody: required: true content: application/json: schema: type: object properties: input: type: string maxLength: 8000 description: >- What the person says, up to 8,000 characters. Can be empty when the message has attachments or answers a form (`action`), and is left out with a decision (`approval`, `answer`). conversation_id: type: string opening: type: string maxLength: 500 description: >- For a new conversation (no conversation_id), the agent's first message, shown as said before the person wrote and recorded as the agent's. Used only when the agent has no first message of its own. variables: type: object maxProperties: 50 additionalProperties: type: - string - number - boolean maxLength: 1000 description: >- For a new conversation (no conversation_id): what it starts knowing, like `{ "customer_name": "Ana", "account_id": "A-77" }`. Names are lowercase letters, numbers and _ (up to 40), values text up to 1,000 characters. The agent reads them with Eager's own (`current_date`, `current_time`, `day_of_week`, `time_zone`, `language`, `channel`, `conversation_id`, `agent_name`, and where known `caller_number`, `agent_number`, `page_url`, `user_name`, `user_email`) and doesn't ask for them; a procedure's input of the same name is taken as given. Eager's own names can't be passed, except `time_zone` (an IANA zone; the date and time are where the person is) and `language`. Sent with a conversation_id, it's a 400. stream: type: boolean version: description: >- `draft`, or a version number, for this turn only. Default: the published version. oneOf: - const: draft - type: integer metadata: type: object description: >- Your own values for a new conversation (a JSON object, up to 4,000 characters). Only used when the conversation is created. attachments: type: array maxItems: 10 items: type: string description: >- Files the person attached: upload ids (`upl_…`) from POST /v1/uploads, up to 10. Images and PDFs the model sees, text files it reads; any other file needs Run code (`tools.code`, Claude or GPT models). A file sent in one conversation can’t be sent in another. action: type: object description: >- Answers a form the agent showed (a `ui` item): `{ name: "submit", surfaceId, context: { : value } }`, or the same wrapped as `{ version: "v0.9", action }`. Needs `conversation_id`. The answers reach the agent as the person’s message; `input`, if sent too, is added after them. 404 for an unknown form, 409 if it was answered already. Or decides a request, as `approval` and `answer` do: on an `approval` item’s surface (`surface_id`), `name` is `approve` or `deny`; on a `question` item’s, its form’s `submit` (`context: { answer: ["