Agent
智能体任务、事件流、确认与会话。
Base URL https://api.sniphunter.com
请求与响应中的 $ref 在 OpenAPI 的 components 中定义。
9 个接口
Agent
GET/api/v1/agent/sessionsList Agent Sessions
List agent sessions for the current user.
{
"security": [
{
"HTTPBearer": []
}
],
"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"
}
}
}
}
}
}DELETE/api/v1/agent/sessions/{session_id}Delete Agent Session
Delete a session and clear its cached engine.
{
"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"
}
}
}
}
}
}GET/api/v1/agent/sessions/{session_id}/messagesGet Session Messages
Get message history for a session.
{
"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"
}
}
}
}
}
}POST/api/v1/agent/tasksRun Agent Task
Submit a new agent task. Requires authentication.
{
"security": [
{
"HTTPBearer": []
}
],
"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"
}
}
}
}
}
}GET/api/v1/agent/tasks/{task_id}Get Agent Task
Get the status and result of an agent task. Requires authentication.
{
"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"
}
}
}
}
}
}POST/api/v1/agent/tasks/{task_id}/cancelCancel Agent Task
Cancel a running agent task.
{
"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"
}
}
}
}
}
}POST/api/v1/agent/tasks/{task_id}/confirmConfirm Tool Execution
Confirm or reject a high-cost tool execution that is awaiting user authorization. The agent loop is suspended at the tool's check_permissions=ASK stage. This endpoint resolves the pending confirmation, allowing the loop to either proceed with tool execution (approved=True) or skip it (approved=False).
{
"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"
}
}
}
}
}
}GET/api/v1/agent/tasks/{task_id}/pending-confirmationsGet Pending Confirmations
Get all pending tool confirmations for a task.
{
"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"
}
}
}
}
}
}GET/api/v1/agent/tasks/{task_id}/streamStream Agent Task
Stream agent task updates using SSE. Supports two frame types: - **Snapshot frames** (default, no ``event:`` field): full ``AgentTaskResponse`` JSON. Sent on every task state change. - **Incremental frames** (typed with ``event:`` field): granular events like ``text_delta``, ``tool_use``, ``tool_result``, ``confirmation_request``, ``confirmation_result``, ``assistant_message``, ``terminal``. The stream stays open during ``awaiting_confirmation``; it closes on ``completed``, ``failed``, or ``cancelled``.
{
"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"
}
}
}
}
}
}数据模型
展开 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"
}
}
}