trustgraph/specs/api/paths/flow/agent.yaml

post:
  tags:
    - Flow Services
  summary: Agent service - conversational AI with reasoning
  description: |
    AI agent that can understand questions, reason about them, and take actions.

    ## Agent Overview

    The agent service provides a conversational AI that:
    - Understands natural language questions
    - Reasons about problems using thoughts
    - Takes actions to gather information
    - Provides coherent answers

    ## Request Format

    Send a question with optional:
    - **state**: Continue from previous conversation
    - **history**: Previous agent steps for context
    - **group**: Collaborative agent identifiers
    - **streaming**: Enable streaming responses

    ## Response Modes

    ### Streaming Mode (streaming: true)
    Responses arrive as chunks with `chunk-type`:
    - `thought`: Agent's reasoning process
    - `action`: Action being taken
    - `observation`: Result from action
    - `answer`: Final response to user
    - `explain`: Provenance event with inline triples (`explain_triples`)
    - `error`: Error occurred

    Each chunk may have multiple messages. Check flags:
    - `end-of-message`: Current chunk type complete
    - `end-of-dialog`: Entire conversation complete

    ### Legacy Mode (streaming: false)
    Single response with:
    - `answer`: Complete answer
    - `thought`: Reasoning (if any)
    - `observation`: Observations (if any)

    ## Multi-turn Conversations

    Include `history` array with previous steps to maintain context.
    Each step has: thought, action, arguments, observation.

  operationId: agentService
  security:
    - bearerAuth: []
  parameters:
    - name: flow
      in: path
      required: true
      schema:
        type: string
      description: Flow instance ID
      example: my-flow
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../../components/schemas/agent/AgentRequest.yaml'
        examples:
          simpleQuestion:
            summary: Simple question
            value:
              question: What is the capital of France?
              user: alice
          streamingQuestion:
            summary: Question with streaming enabled
            value:
              question: Explain quantum computing
              user: alice
              streaming: true
          conversationWithHistory:
            summary: Multi-turn conversation
            value:
              question: And what about its population?
              user: alice
              history:
                - thought: User is asking about the capital of France
                  action: search
                  arguments:
                    query: "capital of France"
                  observation: "Paris is the capital of France"
                  user: alice
  responses:
    '200':
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/agent/AgentResponse.yaml'
          examples:
            streamingThought:
              summary: Streaming thought chunk
              value:
                chunk-type: thought
                content: I need to search for information about quantum computing
                end-of-message: false
                end-of-dialog: false
            streamingAnswer:
              summary: Streaming answer chunk
              value:
                chunk-type: answer
                content: Quantum computing uses quantum mechanics principles...
                end-of-message: false
                end-of-dialog: false
            streamingComplete:
              summary: Streaming complete marker
              value:
                chunk-type: answer
                content: ""
                end-of-message: true
                end-of-dialog: true
            explainEvent:
              summary: Explain event with inline provenance triples
              value:
                chunk-type: explain
                content: ""
                explain_id: urn:trustgraph:agent:abc123
                explain_graph: urn:graph:retrieval
                explain_triples:
                  - s: {t: i, i: "urn:trustgraph:agent:abc123"}
                    p: {t: i, i: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"}
                    o: {t: i, i: "https://trustgraph.ai/ns/AgentSession"}
                  - s: {t: i, i: "urn:trustgraph:agent:abc123"}
                    p: {t: i, i: "https://trustgraph.ai/ns/query"}
                    o: {t: l, v: "Explain quantum computing"}
                end-of-message: true
                end-of-dialog: false
            legacyResponse:
              summary: Legacy non-streaming response
              value:
                answer: Paris is the capital of France.
                thought: User is asking about the capital of France
                observation: ""
                end-of-message: false
                end-of-dialog: false
    '401':
      $ref: '../../components/responses/Unauthorized.yaml'
    '500':
      $ref: '../../components/responses/Error.yaml'