> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt > Use this file to discover all available pages before exploring further. # Chat with one agent in a test conversation > Starts or continues a TEST CONVERSATION with ONE agent — a draft included, which is what this is for: chat with an agent you just created or edited before a human publishes it. Each call is one turn: you send what the customer would say, the agent answers. The first call opens a new conversation and returns its `threadId`; send that `threadId` back on the following calls to keep talking in the same conversation — the agent remembers everything already said in it, so you can test follow-up questions, corrections and multi-step flows the way a real customer would go through them. Omit `threadId` to start over from scratch. The agent runs isolated: only its own prompt, tools and knowledge, with NONE of the ClaudIA pipeline around it (no classification, no hand-off rules, no ticket, and nothing reaches a customer or an inbox) — to see what a customer would actually receive from the whole pipeline, use runPlayground. This call spends real model tokens on the tenant's account. It blocks until the agent is done, which is seconds to a couple of minutes. `id`/`role` are the same pair getAssistant takes. ## OpenAPI ````yaml api-reference/specs/claudia/v1.json POST /v1/tenants/{tenant}/assistants/{id}/invoke openapi: 3.0.1 info: title: Claudia API version: 1.0.0 servers: - url: https://api.cloudhumans.com/claudia description: Production - url: https://api.cloudhumans.com/claudia/staging description: Staging security: - bearerAuth: [] tags: - name: MCP Servers description: >- The MCP servers your agents can call tools on. Registering one here is what makes its tools selectable in an agent; the credentials it needs are stored encrypted and never read back. - name: Knowledge Base Content description: Read, search and edit the content that answers your customers. - name: Content Quality description: Rewrites proposed for content that is answering your customers badly. - name: Playground description: >- Talk to one of your agents as if you were a customer, without touching a real conversation. - name: Project Settings description: >- Read and change how a ClaudIA project behaves — the settings screens of the ClaudIA app, as an API. - name: Content Improvements description: Answers Claudia proposes for questions your content does not cover yet. - name: Knowledge Bases description: The knowledge bases your account can manage. - name: Content Sources description: The sites Claudia crawls to keep a knowledge base in sync. - name: Agents description: >- The AI agents (assistants) configured for your tenant: the orchestrator (supervisor) and its specialists (react). Reads answer the same passthrough shape the platform stores; creates land as DRAFTS a human reviews and publishes in the app. - name: Agent Tools description: >- The tool catalog your agents can be given, aggregated across every MCP server registered for the tenant. This is the same catalog an assistant's mcp_servers[].tools whitelist is validated against. - name: Conversations description: >- Read access to a conversation's lean investigation summary — messages, status and resolution — and the execution trace behind one of its processed messages, without the internal processing state the hub UI's full read carries. paths: /v1/tenants/{tenant}/assistants/{id}/invoke: post: tags: - Agents summary: Chat with one agent in a test conversation description: >- Starts or continues a TEST CONVERSATION with ONE agent — a draft included, which is what this is for: chat with an agent you just created or edited before a human publishes it. Each call is one turn: you send what the customer would say, the agent answers. The first call opens a new conversation and returns its `threadId`; send that `threadId` back on the following calls to keep talking in the same conversation — the agent remembers everything already said in it, so you can test follow-up questions, corrections and multi-step flows the way a real customer would go through them. Omit `threadId` to start over from scratch. The agent runs isolated: only its own prompt, tools and knowledge, with NONE of the ClaudIA pipeline around it (no classification, no hand-off rules, no ticket, and nothing reaches a customer or an inbox) — to see what a customer would actually receive from the whole pipeline, use runPlayground. This call spends real model tokens on the tenant's account. It blocks until the agent is done, which is seconds to a couple of minutes. `id`/`role` are the same pair getAssistant takes. operationId: invokeAssistant parameters: - name: tenant in: path description: >- Tenant whose agents you are managing. Discover the tenants your credentials cover with `listMyClaudiaProjects`. A tenant your credentials do not cover is indistinguishable from one that does not exist. required: true schema: type: string - name: id in: path description: >- Assistant to operate on, as returned by listAssistants (`assistant_id` field). required: true schema: type: string requestBody: description: The message to send, and which deployment the agent lives in. content: application/json: schema: $ref: '#/components/schemas/AssistantInvokeRequest' required: true responses: '200': description: The turn finished and this is what the agent answered. content: application/json: schema: $ref: '#/components/schemas/AssistantInvokeResponse' '400': description: >- The request cannot be run as written: an empty `message`, a `role` that is not `supervisor`, `react` or `qna`, a `threadId` that is not a thread id, or an agent that belongs to no project. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, expired or invalid credentials. '403': description: The credentials hold no account allowed to manage this content. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- No such resource, or none these credentials can reach — the two are deliberately indistinguishable. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- `id` is not a full assistant id — typically a truncated one echoed back from an earlier answer. Carries `error` (`invalid_assistant_id`) and `message`, which names the full candidates the prefix matches so you can retry with one of them. content: application/json: schema: type: object properties: error: type: string description: >- Machine-readable cause — always `invalid_assistant_id` on this response. message: type: string description: >- Names the full assistant ids the truncated one you sent matches, with each candidate's deployment role. additionalProperties: true description: >- Carries `error` (always `invalid_assistant_id`) and `message`, which names the full assistant ids the truncated one you sent matches, with each candidate's deployment role. '429': description: Rate limit applied by the API gateway. Back off and retry. '502': description: >- The run itself failed; the body names the runtime's error code. Retrying is reasonable; the same failure twice points at the agent's configuration. content: application/json: schema: $ref: '#/components/schemas/Error' '504': description: >- The agent was still working when the run budget ran out (`RUN_TIMED_OUT`). Nothing partial is returned. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: AssistantInvokeRequest: required: - message - role type: object properties: role: enum: - supervisor - react - qna type: string description: >- Deployment the assistant lives in — the `deployment_role` listAssistants returns for it: `supervisor`, `react`, or `qna` for a knowledge-base Q&A agent (which runs on the react deployment). Any other value answers 400. example: react message: type: string description: >- What the customer says this turn, verbatim and in the customer's own language. One turn per call: to keep the conversation going, send the next message with the `threadId` you got back. example: meu pedido 12345 ainda não chegou, o que houve? threadId: type: string description: >- Thread of the test conversation to continue. Pass the `threadId` from the previous response and the agent answers with everything already said in that conversation in mind — this is how you send several messages to the same agent in sequence. Omit it to start a new conversation. nullable: true example: 6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d description: >- One turn of a test conversation with a single agent: the message to send, and the thread to continue when there is one. AssistantInvokeResponse: required: - messages - reply type: object properties: threadId: type: string description: >- The test conversation this turn belongs to. Send it back as `threadId` on the next call to keep talking with the same history; a new one is created whenever you omit it. nullable: true example: 6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d reply: type: string description: >- The text of the agent's last reply in this turn. Empty when the turn ended without an assistant message — read `messages` then. example: Seu pedido 12345 saiu para entrega ontem e chega até amanhã. messages: type: array description: >- The whole test conversation so far, as the runtime stores it: every human, ai and tool message of the thread in order, earlier turns included, each with `type` and `content`. Free-form objects — read the keys rather than assuming a shape. items: type: object description: One message of the thread, as the runtime stores it. description: >- One turn of the test conversation: what the agent answered, the thread to continue it, and the whole history so far. Error: required: - error type: object properties: error: type: string description: What went wrong. example: 'Forbidden: token holds no claim for the requested account' description: Something the caller needs to fix. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````