> ## Documentation Index > Fetch the complete documentation index at: https://docs.intelligence-management-platform.com/llms.txt > Use this file to discover all available pages before exploring further. # Run an agent > Sends a message to an agent instance and returns the response. When the `stream` header is `true`, the response is an AI SDK UIMessage stream over SSE (text/event-stream); otherwise a sync JSON response is returned. The agent's `rights_mode` controls whether an API key or session JWT is required — public agents allow unauthenticated calls. An agent-scoped API key is only valid for its bound agent instance. Supply the `session` header to persist messages to a session. ## OpenAPI ````yaml /openapi/openapi.json post /agents/litellm/run/{instance} openapi: 3.1.0 info: title: IMP REST API version: 1.0.0 description: >- REST endpoints of the IMP backend. GraphQL covers entity CRUD; REST covers agent runs, media, files, and system utilities. All requests require authentication unless the agent is public. servers: - url: '{baseUrl}' variables: baseUrl: default: http://localhost:9001 description: >- Base URL of your IMP backend. Self-hosted deployments typically run on port 9001. security: - apiKey: [] - bearer: [] tags: - name: Agents description: Endpoints for running, compacting, and querying agent instances. - name: Sessions description: Endpoints for managing files attached to agent sessions. - name: Media description: Transcription, speech synthesis, and image generation. - name: System description: Platform health and configuration utilities. - name: Budgets description: >- LiteLLM tag-budget management for users, roles, teams, projects, agents, and routines. Access requires `super_admin` or a role with `budget_management` write scope. - name: Skills description: >- Skills are versioned bundles of files (markdown, scripts, assets) mounted into the agent sandbox. These endpoints manage the skill registry and individual skill files. - name: Uploads description: >- Uppy-compatible S3 companion routes for single-part and multipart file uploads. Accept the standard API key. The `internal-key` header (set to `INTERNAL_SECRET`) is accepted only on `/s3/delete`, `/s3/download`, `/s3/list`, and `/s3/object` — it does **not** work on `/s3/sign` or the `/s3/multipart` routes. - name: Compliance description: >- GDPR / DSGVO operator endpoints for data-subject access (export) and erasure. Both require `super_admin`. - name: Artifacts description: >- Shareable artifact links — create, list, and revoke share links for files stored in S3. paths: /agents/litellm/run/{instance}: post: tags: - Agents summary: Run an agent description: >- Sends a message to an agent instance and returns the response. When the `stream` header is `true`, the response is an AI SDK UIMessage stream over SSE (text/event-stream); otherwise a sync JSON response is returned. The agent's `rights_mode` controls whether an API key or session JWT is required — public agents allow unauthenticated calls. An agent-scoped API key is only valid for its bound agent instance. Supply the `session` header to persist messages to a session. operationId: runAgent parameters: - name: instance in: path required: true description: Agent ID (UUID). schema: type: string format: uuid - name: stream in: header required: false description: >- Set to `true` to receive a streaming SSE response (AI SDK UIMessage stream). Omit or set to `false` for a synchronous JSON response. schema: type: string enum: - 'true' - 'false' default: 'false' - name: session in: header required: false description: >- Agent session ID. When provided, message history is loaded from and saved to the session. The caller must have write access to the session. schema: type: string format: uuid - name: x-exulu-model-override in: header required: false description: >- LiteLLM model ID to use for this request, overriding the model configured on the agent. Only accepted when the resolved model is permitted for the calling user. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: message: $ref: '#/components/schemas/UIMessage' description: >- The user message to send. Used when `session` is set or when sending a single message without history. messages: type: array items: $ref: '#/components/schemas/UIMessage' description: >- Full conversation history. When provided without a `session` header and without a `message` field, the last element is used as the current message and the rest as prior context. customInstructions: type: string description: >- Additional system instructions appended to the agent's base instructions for this run only. disabledTools: type: array items: type: string description: >- Tool IDs to exclude from this run, even if enabled on the agent. disabledSkills: type: array items: type: string description: Skill IDs to exclude from this run. approvedTools: type: array items: type: string description: >- Tool call IDs that the user has pre-approved for execution without a confirmation prompt. examples: streaming: summary: Streaming run with session value: message: id: msg_01Ab2Cd3Ef4Gh5 role: user parts: - type: text text: Summarise last quarter's revenue figures. sync: summary: Synchronous run without session value: message: id: msg_01Ab2Cd3Ef4Gh5 role: user parts: - type: text text: What is the capital of France? responses: '200': description: >- Successful response. When `stream: true` the body is an AI SDK UIMessage stream (text/event-stream); each line is a server-sent event carrying a UIMessage part or finish chunk. When `stream: false` the body is a sync JSON object returned by `provider.generateSync`. content: text/event-stream: schema: type: string description: >- AI SDK UIMessage stream. Lines are SSE events; each event carries a serialised UIMessage part (text delta, tool-call, tool-result, finish-step, finish). The final `finish` event includes token usage in its `messageMetadata`. example: > 0:{"id":"msg_01Ab","role":"assistant","parts":[]} 2:{"type":"text-delta","textDelta":"Paris"} 9:{"finishReason":"stop","usage":{"inputTokens":42,"outputTokens":3}} application/json: schema: type: string description: The assistant's final text as a JSON-encoded string. '400': description: >- Missing or invalid request parameters (missing instance, missing model on agent, bad scope, request validation error). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: >- Authentication failed or caller lacks read access to the agent or write access to the session. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Model not permitted for the calling user or agent-scoped key used against a different agent. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Agent with the given `instance` ID not found. content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: >- Context window is full and compaction is required before the next message can be sent. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: bash label: cURL — streaming source: >- curl -X POST https://your-imp-host/agents/litellm/run/d4f7a2e1-6c3b-4a9e-8f21-0b5c9d7e3a10 \ -H "x-api-key: sk_abc123.../my-key" \ -H "Content-Type: application/json" \ -H "stream: true" \ -H "session: e7c3b8a2-0d4f-4b1e-9c72-3a6d5e8f1b20" \ -d '{"message":{"id":"msg_01Ab","role":"user","parts":[{"type":"text","text":"Hello"}]}}' components: schemas: UIMessage: type: object description: >- An AI SDK UIMessage object. Contains an `id` string, a `role` string (`user` | `assistant` | `system` | `tool`), and a `parts` array of part objects (text, tool-call, tool-result, image, etc.). properties: id: type: string role: type: string enum: - user - assistant - system - tool parts: type: array items: type: object required: - id - role - parts Error: type: object properties: detail: type: string description: Human-readable error message. message: type: string description: Human-readable error message (alternate key used on some endpoints). securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- Organisation API key. Format: `sk_/` — the secret portion, a literal slash, and the human-readable key name. The header `exulu-api-key` is accepted as an alias. A `Bearer ` prefix is tolerated and stripped. Keys with an agent scope are only valid for the scoped agent instance. bearer: type: http scheme: bearer bearerFormat: JWT description: >- NextAuth session JWT (HS256, signed with `NEXTAUTH_SECRET`). This is the token the IMP frontend uses automatically. ````