# Agent

Base URL `https://api.sniphunter.com`

智能体任务、事件流、确认与会话。

# Agent


## GET /api/v1/agent/sessions

List Agent Sessions
List agent sessions for the current user.

```json
{
  "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.

```json
{
  "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}/messages

Get Session Messages
Get message history for a session.

```json
{
  "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/tasks

Run Agent Task
Submit a new agent task.
Requires authentication.

```json
{
  "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.

```json
{
  "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}/cancel

Cancel Agent Task
Cancel a running agent task.

```json
{
  "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}/confirm

Confirm 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).

```json
{
  "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-confirmations

Get Pending Confirmations
Get all pending tool confirmations for a task.

```json
{
  "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}/stream

Stream 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``.

```json
{
  "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

```json
{
  "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"
    }
  }
}
```