---
title: "Invoke"
method: POST
path: "/api/v1/agent/invoke"
---

# Invoke

`POST /api/v1/agent/invoke`

## Request

- Base URL: `https://api.twtapi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.twtapi.com/api/v1/agent/invoke`
- Auth: none declared

执行一次 Agent 工具调用（需要 skill_key 鉴权，调用成功即扣费）。

参数:
    body: tool（工具名）、params（工具参数）、session_id（可选，仅用于日志串联）。
    background_tasks: 用于在响应返回后异步写调用日志，不阻塞用户。

返回:
    AgentInvokeResponse(code=200, tool, data, credits_used)。

异常（均为 ApiException，由全局处理器转成统一错误体）:
    404 40420 功能未开启；404 40421 工具不存在；400 40021 必填参数缺失；
    403 40321 被风控拦截；429/503 限流相关（见 _check_limits）；
    402 40201 余额不足；502 50201 上游异常（且已退款）。

## Request body

- AgentInvokeRequest: Agent 接口调用入参。 params 用 default_factory 而非直接 ``= {}``：可变默认值会在 多次请求间共享同一对象，是典型的串数据隐患。 session_id 为空时由服务端开启新会话。
  - `tool` string, required
  - `params` object
  - `session_id` string, nullable

## Response `200`

Successful Response

- AgentInvokeResponse: Agent 接口出参。credits_used 便于前端即时展示本次消耗。
  - `code` integer
  - `tool` string, required
  - `data` unknown
  - `credits_used` number, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/twtapi/apis/twtapi-backend.md) · [All operations](https://skmtc.dev/twtapi/apis/twtapi-backend/llms.txt) · [OpenAPI document](https://skmtc.dev/twtapi/apis/twtapi-backend/revisions/5295976febaf?raw)