REST API OpenAPI spec (#612)

* OpenAPI spec in specs/api.  Checked lint with redoc.

specs/api/components/schemas/agent/AgentRequest.yaml

@@ -0,0 +1,59 @@
+type: object
+description: |
+  Agent service request - conversational AI agent that can reason and take actions.
+required:
+  - question
+properties:
+  question:
+    type: string
+    description: User question or prompt for the agent
+    example: What is the capital of France?
+  state:
+    type: string
+    description: Agent state for continuation (optional, for multi-turn)
+    example: agent-state-12345
+  group:
+    type: array
+    description: Group identifiers for collaborative agents (optional)
+    items:
+      type: string
+    example: ["research-team"]
+  history:
+    type: array
+    description: Conversation history (optional, list of previous agent steps)
+    items:
+      type: object
+      properties:
+        thought:
+          type: string
+          description: Agent's reasoning
+          example: I need to search for information about Paris
+        action:
+          type: string
+          description: Action taken
+          example: search
+        arguments:
+          type: object
+          description: Action arguments
+          additionalProperties:
+            type: string
+          example:
+            query: "capital of France"
+        observation:
+          type: string
+          description: Result of the action
+          example: "Paris is the capital of France"
+        user:
+          type: string
+          description: User context for this step
+          example: alice
+  user:
+    type: string
+    description: User identifier for multi-tenancy
+    default: trustgraph
+    example: alice
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true

specs/api/components/schemas/agent/AgentResponse.yaml

@@ -0,0 +1,51 @@
+type: object
+description: Agent service response (streaming or legacy format)
+properties:
+  chunk-type:
+    type: string
+    description: Type of streaming chunk (streaming mode only)
+    enum:
+      - thought
+      - action
+      - observation
+      - answer
+      - error
+    example: answer
+  content:
+    type: string
+    description: Chunk content (streaming mode only)
+    example: Paris is the capital of France.
+  end-of-message:
+    type: boolean
+    description: Current chunk type is complete (streaming mode)
+    default: false
+    example: true
+  end-of-dialog:
+    type: boolean
+    description: Entire agent dialog is complete (streaming mode)
+    default: false
+    example: true
+  answer:
+    type: string
+    description: Final answer (legacy non-streaming format)
+    example: Paris is the capital of France.
+  thought:
+    type: string
+    description: Agent reasoning (legacy format)
+    example: I should search for information about the capital of France.
+  observation:
+    type: string
+    description: Observation from actions (legacy format)
+    example: Found information about Paris being the capital.
+  error:
+    type: object
+    description: Error details if request failed
+    properties:
+      message:
+        type: string
+        description: Error message
+        example: Failed to process agent request
+      code:
+        type: string
+        description: Error code
+        example: AGENT_ERROR