> ## Documentation Index
> Fetch the complete documentation index at: https://dev-docs.persona.hasanraiyan.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an Agent as an external user, streaming AG-UI events (SSE)

> Requires a ProjectRuntimeContext — the credential must be paired with the x-persona-external-user-id header asserting which of the Project's own external users is running the Agent. Reuses the exact same runtime as the Persona AG-UI route. Pass x-thread-id (a Thread id from POST /api/v1/developer/threads) to resume a named conversation — omit it to keep using the implicit, Domain-extended deterministic thread id (one conversation per Agent + external user). An unrecognized/foreign/wrong-agent x-thread-id silently falls back to the deterministic id rather than erroring (same contract as the Persona AG-UI route).




## OpenAPI

````yaml /openapi.json post /api/v1/developer/agui
openapi: 3.0.0
info:
  title: Persona.ai Developer Platform API
  version: 1.0.0
  description: >-
    REST + AG-UI API for integrating your product with Persona's agent
    infrastructure.


    Every endpoint here is a server-to-server call — see the Integration Guide
    for where in your own stack to call each one from, and how the same endpoint
    serves both Project-level and per-end-user requests via the
    `x-persona-external-user-id` header.
servers:
  - url: https://api.personaai.com
    description: Production
security: []
tags: []
paths:
  /api/v1/developer/agui:
    post:
      tags:
        - Developer
      summary: Run an Agent as an external user, streaming AG-UI events (SSE)
      description: >
        Requires a ProjectRuntimeContext — the credential must be paired with
        the x-persona-external-user-id header asserting which of the Project's
        own external users is running the Agent. Reuses the exact same runtime
        as the Persona AG-UI route. Pass x-thread-id (a Thread id from POST
        /api/v1/developer/threads) to resume a named conversation — omit it to
        keep using the implicit, Domain-extended deterministic thread id (one
        conversation per Agent + external user). An
        unrecognized/foreign/wrong-agent x-thread-id silently falls back to the
        deterministic id rather than erroring (same contract as the Persona
        AG-UI route).
      parameters:
        - name: x-agent-id
          in: header
          required: true
          schema:
            type: string
        - name: x-persona-external-user-id
          in: header
          required: true
          schema:
            type: string
        - name: x-thread-id
          in: header
          required: false
          schema:
            type: string
          description: >-
            A Thread id from the Developer Thread CRUD API — resumes that
            conversation instead of the implicit deterministic one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - assistant
                      content:
                        type: string
                resume:
                  type: object
                  description: >
                    Resume data for a Thread paused on a human-in-the-loop
                    interrupt (e.g. an agent-management tool the Agent's
                    `interruptOn` config requires confirming). Pass { type:
                    "decision", decision: "continue" | "reject" } to
                    approve/deny a pending tool call, or an object shaped for
                    the specific clarification the interrupted run is waiting
                    on.
      responses:
        '200':
          description: >
            A `text/event-stream` SSE stream of AG-UI protocol events (the
            standard `@ag-ui/core` EventType values): RUN_STARTED once at the
            start of the run; TEXT_MESSAGE_CHUNK for streamed assistant text
            deltas; REASONING_MESSAGE_START/CONTENT/END for models that expose
            reasoning; TOOL_CALL_CHUNK/TOOL_CALL_RESULT for tool invocations and
            their results; STATE_SNAPSHOT for full-state updates; CUSTOM for
            Persona-specific side-channel events (e.g. subagent traces, MCP
            structured content); and RUN_FINISHED once at the end. Each event is
            a JSON object sent as one `data: ` line per SSE convention.
        '400':
          description: Missing x-agent-id, or credential has no asserted external user
        '401':
          description: Missing or invalid Project credential
        '403':
          description: Project is not currently ACTIVE
        '404':
          description: Agent not found (or not executable by this Domain/Subject)
      security:
        - projectCredential: []
components:
  securitySchemes:
    projectCredential:
      type: http
      scheme: bearer
      bearerFormat: <keyId>.<secret>
      description: >-
        Developer Platform Project credential, minted via POST
        /api/v1/projects/{projectId}/credentials. Send as `Authorization: Bearer
        <keyId>.<secret>`. Optionally pair with the `x-persona-external-user-id`
        header to act on behalf of one of the Project's own external users. This
        credential is a server-side secret — see the Integration Guide.

````