{ "openapi": "3.1.0", "info": { "title": "Agent", "description": "API service for App Factory reusable modules", "version": "1.0.0", "x-source-commit": "f33cc2b935f31b36240d724948dc8b9c765430cc" }, "paths": { "/api/v1/agent/tasks": { "post": { "tags": [ "agent" ], "summary": "Run Agent Task", "description": "Submit a new agent task.\nRequires authentication.", "operationId": "run_agent_task_api_v1_agent_tasks_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/agent/tasks/{task_id}": { "get": { "tags": [ "agent" ], "summary": "Get Agent Task", "description": "Get the status and result of an agent task.\nRequires authentication.", "operationId": "get_agent_task_api_v1_agent_tasks__task_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/tasks/{task_id}/stream": { "get": { "tags": [ "agent" ], "summary": "Stream Agent Task", "description": "Stream agent task updates using SSE.\n\nSupports two frame types:\n- **Snapshot frames** (default, no ``event:`` field): full ``AgentTaskResponse`` JSON.\n Sent on every task state change.\n- **Incremental frames** (typed with ``event:`` field): granular events like\n ``text_delta``, ``tool_use``, ``tool_result``, ``confirmation_request``,\n ``confirmation_result``, ``assistant_message``, ``terminal``.\n\nThe stream stays open during ``awaiting_confirmation``; it closes on\n``completed``, ``failed``, or ``cancelled``.", "operationId": "stream_agent_task_api_v1_agent_tasks__task_id__stream_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Stream Agent Task Api V1 Agent Tasks Task Id Stream Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/tasks/{task_id}/confirm": { "post": { "tags": [ "agent" ], "summary": "Confirm Tool Execution", "description": "Confirm or reject a high-cost tool execution that is awaiting user authorization.\n\nThe agent loop is suspended at the tool's check_permissions=ASK stage.\nThis endpoint resolves the pending confirmation, allowing the loop to\neither proceed with tool execution (approved=True) or skip it (approved=False).", "operationId": "confirm_tool_execution_api_v1_agent_tasks__task_id__confirm_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolConfirmRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Confirm Tool Execution Api V1 Agent Tasks Task Id Confirm Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/tasks/{task_id}/pending-confirmations": { "get": { "tags": [ "agent" ], "summary": "Get Pending Confirmations", "description": "Get all pending tool confirmations for a task.", "operationId": "get_pending_confirmations_api_v1_agent_tasks__task_id__pending_confirmations_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Get Pending Confirmations Api V1 Agent Tasks Task Id Pending Confirmations Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/tasks/{task_id}/cancel": { "post": { "tags": [ "agent" ], "summary": "Cancel Agent Task", "description": "Cancel a running agent task.", "operationId": "cancel_agent_task_api_v1_agent_tasks__task_id__cancel_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Cancel Agent Task Api V1 Agent Tasks Task Id Cancel Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/sessions": { "get": { "tags": [ "agent" ], "summary": "List Agent Sessions", "description": "List agent sessions for the current user.", "operationId": "list_agent_sessions_api_v1_agent_sessions_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AgentSessionSummary" }, "type": "array", "title": "Response List Agent Sessions Api V1 Agent Sessions Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/agent/sessions/{session_id}/messages": { "get": { "tags": [ "agent" ], "summary": "Get Session Messages", "description": "Get message history for a session.", "operationId": "get_session_messages_api_v1_agent_sessions__session_id__messages_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSessionMessage" }, "title": "Response Get Session Messages Api V1 Agent Sessions Session Id Messages Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/sessions/{session_id}": { "delete": { "tags": [ "agent" ], "summary": "Delete Agent Session", "description": "Delete a session and clear its cached engine.", "operationId": "delete_agent_session_api_v1_agent_sessions__session_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Delete Agent Session Api V1 Agent Sessions Session Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AgentSessionMessage": { "properties": { "role": { "type": "string", "title": "Role" }, "content": { "type": "string", "title": "Content", "default": "" }, "tool_calls": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Tool Calls" }, "tool_call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Call Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "artifacts": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Artifacts" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "role" ], "title": "AgentSessionMessage", "description": "会话历史消息" }, "AgentSessionSummary": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "title": { "type": "string", "title": "Title", "default": "" }, "last_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Message" }, "message_count": { "type": "integer", "title": "Message Count", "default": 0 }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "session_id" ], "title": "AgentSessionSummary", "description": "会话列表项" }, "AgentStep": { "properties": { "step_id": { "type": "string", "title": "Step Id" }, "description": { "type": "string", "title": "Description" }, "status": { "type": "string", "title": "Status" }, "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "step_id", "description", "status" ], "title": "AgentStep" }, "AgentTaskCreate": { "properties": { "query": { "type": "string", "title": "Query", "description": "The user query or task description" }, "task_type": { "$ref": "#/components/schemas/AgentTaskType", "description": "Type of agent task", "default": "general" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id", "description": "Session ID for conversation context" }, "context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context", "description": "Additional context for the task" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mode", "description": "manual: 高耗工具需确认; auto: 自动确认但仍计费" } }, "type": "object", "required": [ "query" ], "title": "AgentTaskCreate" }, "AgentTaskResponse": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "status": { "$ref": "#/components/schemas/AgentTaskStatus" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result" }, "steps": { "items": { "$ref": "#/components/schemas/AgentStep" }, "type": "array", "title": "Steps", "default": [] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "user_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "User Id", "description": "用户 ID（用于权限控制）" }, "pending_confirmation": { "anyOf": [ { "$ref": "#/components/schemas/PendingConfirmationPayload" }, { "type": "null" } ], "description": "当前等待用户确认的高消耗工具（SSE 实时推送）" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id", "description": "关联会话 ID" } }, "type": "object", "required": [ "task_id", "status", "created_at", "updated_at" ], "title": "AgentTaskResponse" }, "AgentTaskStatus": { "type": "string", "enum": [ "pending", "running", "awaiting_confirmation", "completed", "failed", "cancelled" ], "title": "AgentTaskStatus" }, "AgentTaskType": { "type": "string", "enum": [ "research", "coding", "general" ], "title": "AgentTaskType" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "PendingConfirmationPayload": { "properties": { "tool_call_id": { "type": "string", "title": "Tool Call Id" }, "tool_name": { "type": "string", "title": "Tool Name" }, "arguments": { "additionalProperties": true, "type": "object", "title": "Arguments" }, "confirm_message": { "type": "string", "title": "Confirm Message", "default": "" }, "cost_estimate": { "additionalProperties": true, "type": "object", "title": "Cost Estimate" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "tool_call_id", "tool_name" ], "title": "PendingConfirmationPayload", "description": "SSE/HTTP 暴露的待确认工具载荷" }, "ToolConfirmRequest": { "properties": { "tool_call_id": { "type": "string", "title": "Tool Call Id", "description": "待确认的工具调用 ID" }, "approved": { "type": "boolean", "title": "Approved", "description": "是否批准执行" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "确认/拒绝原因" } }, "type": "object", "required": [ "tool_call_id", "approved" ], "title": "ToolConfirmRequest", "description": "用户确认/拒绝高消耗工具执行的请求" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://api.sniphunter.com" } ] }