ai-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Agent

When to Use

适用场景

Use this skill when the user wants to configure AI agents through API calls (no source files, no deploy step) — typically from a dashboard or a backend script that creates/updates the agent imperatively.

If the user wants a code-first agent with custom tool handlers in TypeScript, deployed via the

zavu

CLI, route them to the functions
skill instead. That path is more ergonomic, version-controlled, and has built-in deployment + debugging.

Quick routing:

User says…	Use
"I want my agent's tool to query my database" / "I want to write the tool handler in code" / `defineTool` / `zavu deploy`	`functions` skill
"Set up an agent that calls a webhook on my server" / "Configure from the dashboard" / "Create an agent via API"	this skill
"I'm starting from scratch and want the simplest path"	`functions` skill (recommended default)

The imperative API documented here is fully supported and won't be deprecated, but Functions is the recommended path for most new integrations.

当用户希望通过API调用（无需源文件，无需部署步骤）配置AI Agent时，可使用此技能——通常用于从仪表板或后端脚本中以命令式方式创建/更新Agent。

如果用户希望使用TypeScript构建代码优先的Agent并自定义工具处理器，通过

zavu

CLI部署，请引导他们使用**

functions

**技能。该路径更符合工程习惯、支持版本控制，且内置部署与调试功能。

快速路由指南：

用户需求描述	对应技能
"我想让我的Agent工具查询我的数据库" / "我想用代码编写工具处理器" / `defineTool` / `zavu deploy`	`functions` 技能
"设置一个能调用我服务器Webhook的Agent" / "从仪表板进行配置" / "通过API创建Agent"	本技能
"我从零开始，想要最简单的实现路径"	`functions` 技能（推荐默认选项）

本文档所述的命令式API已完全支持且不会被弃用，但Functions是大多数新集成的推荐路径。

Architecture

架构

Inbound message -> Flow check (keyword/intent match?)
                     -> YES: Execute flow steps
                     -> NO: LLM call with system prompt + context + KB
                -> Agent generates response -> Send reply

入站消息 -> 流程检查（是否匹配关键词/意图？）
                     -> 是：执行流程步骤
                     -> 否：结合系统提示词+上下文+知识库调用LLM
                -> Agent生成响应 -> 发送回复

Create Agent

创建Agent

Each sender can have one agent:

typescript

const result = await zavu.senders.agent.create({
  senderId: "snd_abc123",
  name: "Customer Support",
  provider: "openai",
  model: "gpt-4o-mini",
  systemPrompt: "You are a helpful customer support agent for Acme Corp. Be friendly, concise, and helpful. If you don't know the answer, say so.",
  apiKey: process.env.PROVIDER_API_KEY,
  contextWindowMessages: 10,
  includeContactMetadata: true,
  triggerOnChannels: ["sms", "whatsapp"],
  triggerOnMessageTypes: ["text"],
});
console.log(result.agent.id); // agent_xxx

Python:

python

result = zavu.senders.agent.create(
    sender_id="snd_abc123",
    name="Customer Support",
    provider="openai",
    model="gpt-4o-mini",
    system_prompt="You are a helpful customer support agent...",
    api_key=os.environ["PROVIDER_API_KEY"],
)

Go:

result, err := client.Senders.Agent.Create(context.TODO(), zavudev.AgentCreateParams{
    SenderID:     zavudev.String("snd_abc123"),
    Name:         zavudev.String("Customer Support"),
    Provider:     zavudev.String("openai"),
    Model:        zavudev.String("gpt-4o-mini"),
    SystemPrompt: zavudev.String("You are a helpful customer support agent..."),
    APIKey:       zavudev.String(os.Getenv("PROVIDER_API_KEY")),
})

Ruby:

ruby

result = client.senders.agent.create(
    sender_id: "snd_abc123",
    name: "Customer Support",
    provider: "openai",
    model: "gpt-4o-mini",
    system_prompt: "You are a helpful customer support agent...",
    api_key: ENV["PROVIDER_API_KEY"],
)

PHP:

php

$result = $client->senders->agent->create([
    'senderId' => 'snd_abc123',
    'name' => 'Customer Support',
    'provider' => 'openai',
    'model' => 'gpt-4o-mini',
    'systemPrompt' => 'You are a helpful customer support agent...',
    'apiKey' => getenv('PROVIDER_API_KEY'),
]);

每个发送方只能拥有一个Agent：

typescript

const result = await zavu.senders.agent.create({
  senderId: "snd_abc123",
  name: "Customer Support",
  provider: "openai",
  model: "gpt-4o-mini",
  systemPrompt: "You are a helpful customer support agent for Acme Corp. Be friendly, concise, and helpful. If you don't know the answer, say so.",
  apiKey: process.env.PROVIDER_API_KEY,
  contextWindowMessages: 10,
  includeContactMetadata: true,
  triggerOnChannels: ["sms", "whatsapp"],
  triggerOnMessageTypes: ["text"],
});
console.log(result.agent.id); // agent_xxx

Python:

python

result = zavu.senders.agent.create(
    sender_id="snd_abc123",
    name="Customer Support",
    provider="openai",
    model="gpt-4o-mini",
    system_prompt="You are a helpful customer support agent...",
    api_key=os.environ["PROVIDER_API_KEY"],
)

Go:

result, err := client.Senders.Agent.Create(context.TODO(), zavudev.AgentCreateParams{
    SenderID:     zavudev.String("snd_abc123"),
    Name:         zavudev.String("Customer Support"),
    Provider:     zavudev.String("openai"),
    Model:        zavudev.String("gpt-4o-mini"),
    SystemPrompt: zavudev.String("You are a helpful customer support agent..."),
    APIKey:       zavudev.String(os.Getenv("PROVIDER_API_KEY")),
})

Ruby:

ruby

result = client.senders.agent.create(
    sender_id: "snd_abc123",
    name: "Customer Support",
    provider: "openai",
    model: "gpt-4o-mini",
    system_prompt: "You are a helpful customer support agent...",
    api_key: ENV["PROVIDER_API_KEY"],
)

PHP:

php

$result = $client->senders->agent->create([
    'senderId' => 'snd_abc123',
    'name' => 'Customer Support',
    'provider' => 'openai',
    'model' => 'gpt-4o-mini',
    'systemPrompt' => 'You are a helpful customer support agent...',
    'apiKey' => getenv('PROVIDER_API_KEY'),
]);

Provider & Model Selection

服务商与模型选择

Provider	Models	API Key Required
`openai`	`gpt-4o` , `gpt-4o-mini` , `gpt-4-turbo`	Yes
`anthropic`	`claude-3-5-sonnet` , `claude-3-haiku`	Yes
`google`	`gemini-1.5-pro` , `gemini-1.5-flash`	Yes
`mistral`	`mistral-large` , `mistral-small`	Yes
`zavu`	Zavu-hosted models	No (included)

服务商	模型	是否需要API密钥
`openai`	`gpt-4o` , `gpt-4o-mini` , `gpt-4-turbo`	是
`anthropic`	`claude-3-5-sonnet` , `claude-3-haiku`	是
`google`	`gemini-1.5-pro` , `gemini-1.5-flash`	是
`mistral`	`mistral-large` , `mistral-small`	是
`zavu`	Zavu托管模型	否（已包含）

Update & Toggle Agent

更新与启用/禁用Agent

typescript

// Update configuration
await zavu.senders.agent.update({
  senderId: "snd_abc123",
  systemPrompt: "Updated prompt...",
  temperature: 0.7,
  maxTokens: 500,
});

// Enable/disable
await zavu.senders.agent.update({
  senderId: "snd_abc123",
  enabled: false,
});

typescript

// 更新配置
await zavu.senders.agent.update({
  senderId: "snd_abc123",
  systemPrompt: "Updated prompt...",
  temperature: 0.7,
  maxTokens: 500,
});

// 启用/禁用
await zavu.senders.agent.update({
  senderId: "snd_abc123",
  enabled: false,
});

Conversational Flows

对话流程

Flows handle structured conversations (keyword triggers, data collection):

typescript

const result = await zavu.senders.agent.flows.create({
  senderId: "snd_abc123",
  name: "Lead Capture",
  description: "Capture lead information from interested prospects",
  trigger: {
    type: "keyword",
    keywords: ["info", "pricing", "demo"],
  },
  steps: [
    {
      id: "welcome",
      type: "message",
      config: { text: "Thanks for your interest! Let me get some info." },
      nextStepId: "ask_name",
    },
    {
      id: "ask_name",
      type: "collect",
      config: { variable: "name", prompt: "What's your name?" },
      nextStepId: "ask_email",
    },
    {
      id: "ask_email",
      type: "collect",
      config: { variable: "email", prompt: "What's your email?" },
      nextStepId: "confirm",
    },
    {
      id: "confirm",
      type: "message",
      config: { text: "Thanks {{name}}! We'll reach out at {{email}}." },
    },
  ],
  enabled: true,
  priority: 10,
});

流程用于处理结构化对话（关键词触发、数据收集）：

typescript

const result = await zavu.senders.agent.flows.create({
  senderId: "snd_abc123",
  name: "Lead Capture",
  description: "Capture lead information from interested prospects",
  trigger: {
    type: "keyword",
    keywords: ["info", "pricing", "demo"],
  },
  steps: [
    {
      id: "welcome",
      type: "message",
      config: { text: "Thanks for your interest! Let me get some info." },
      nextStepId: "ask_name",
    },
    {
      id: "ask_name",
      type: "collect",
      config: { variable: "name", prompt: "What's your name?" },
      nextStepId: "ask_email",
    },
    {
      id: "ask_email",
      type: "collect",
      config: { variable: "email", prompt: "What's your email?" },
      nextStepId: "confirm",
    },
    {
      id: "confirm",
      type: "message",
      config: { text: "Thanks {{name}}! We'll reach out at {{email}}." },
    },
  ],
  enabled: true,
  priority: 10,
});

Trigger Types

触发类型

Type	Description
`keyword`	Matches specific keywords in message
`intent`	Matches detected intent
`always`	Runs on every message
`manual`	Only triggered via API

类型	描述
`keyword`	匹配消息中的特定关键词
`intent`	匹配检测到的意图
`always`	对每条消息都执行
`manual`	仅通过API触发

Step Types

步骤类型

Type	Description
`message`	Send a message
`collect`	Collect user input into a variable
`condition`	Branch based on conditions
`tool`	Call a webhook tool
`llm`	Make an LLM call
`transfer`	Transfer to human agent

类型	描述
`message`	发送消息
`collect`	将用户输入收集到变量中
`condition`	根据条件分支
`tool`	调用Webhook工具
`llm`	调用LLM
`transfer`	转接至人工Agent

Flow Operations

流程操作

typescript

// List flows
const flows = await zavu.senders.agent.flows.list({ senderId: "snd_abc123" });

// Update flow
await zavu.senders.agent.flows.update({
  senderId: "snd_abc123",
  flowId: "flow_abc123",
  enabled: false,
});

// Duplicate flow
await zavu.senders.agent.flows.duplicate({
  senderId: "snd_abc123",
  flowId: "flow_abc123",
  newName: "Lead Capture (Copy)",
});

// Delete flow
await zavu.senders.agent.flows.delete({
  senderId: "snd_abc123",
  flowId: "flow_abc123",
});

typescript

// 列出流程
const flows = await zavu.senders.agent.flows.list({ senderId: "snd_abc123" });

// 更新流程
await zavu.senders.agent.flows.update({
  senderId: "snd_abc123",
  flowId: "flow_abc123",
  enabled: false,
});

// 复制流程
await zavu.senders.agent.flows.duplicate({
  senderId: "snd_abc123",
  flowId: "flow_abc123",
  newName: "Lead Capture (Copy)",
});

// 删除流程
await zavu.senders.agent.flows.delete({
  senderId: "snd_abc123",
  flowId: "flow_abc123",
});

Webhook Tools

Webhook工具

Tools let the agent call your backend during conversations:

typescript

const result = await zavu.senders.agent.tools.create({
  senderId: "snd_abc123",
  name: "get_order_status",
  description: "Get the current status of a customer order",
  webhookUrl: "https://api.example.com/webhooks/order-status",
  webhookSecret: process.env.WEBHOOK_SECRET,
  parameters: {
    type: "object",
    properties: {
      order_id: { type: "string", description: "The order ID to look up" },
    },
    required: ["order_id"],
  },
});

// Test tool
await zavu.senders.agent.tools.test({
  senderId: "snd_abc123",
  toolId: "tool_abc123",
  testParams: { order_id: "ORD-12345" },
});

工具允许Agent在对话过程中调用你的后端服务：

typescript

const result = await zavu.senders.agent.tools.create({
  senderId: "snd_abc123",
  name: "get_order_status",
  description: "Get the current status of a customer order",
  webhookUrl: "https://api.example.com/webhooks/order-status",
  webhookSecret: process.env.WEBHOOK_SECRET,
  parameters: {
    type: "object",
    properties: {
      order_id: { type: "string", description: "The order ID to look up" },
    },
    required: ["order_id"],
  },
});

// 测试工具
await zavu.senders.agent.tools.test({
  senderId: "snd_abc123",
  toolId: "tool_abc123",
  testParams: { order_id: "ORD-12345" },
});

Knowledge Bases (RAG)

知识库（RAG）

Add documents for the agent to reference via retrieval-augmented generation:

typescript

// Create knowledge base
const kb = await zavu.senders.agent.knowledgeBases.create({
  senderId: "snd_abc123",
  name: "Product FAQ",
  description: "Frequently asked questions about our products",
});

// Add document
await zavu.senders.agent.knowledgeBases.documents.create({
  senderId: "snd_abc123",
  kbId: kb.knowledgeBase.id,
  title: "Return Policy",
  content: "Our return policy allows returns within 30 days of purchase...",
});

// List documents
const docs = await zavu.senders.agent.knowledgeBases.documents.list({
  senderId: "snd_abc123",
  kbId: kb.knowledgeBase.id,
});

添加文档供Agent通过检索增强生成（RAG）功能参考：

typescript

// 创建知识库
const kb = await zavu.senders.agent.knowledgeBases.create({
  senderId: "snd_abc123",
  name: "Product FAQ",
  description: "Frequently asked questions about our products",
});

// 添加文档
await zavu.senders.agent.knowledgeBases.documents.create({
  senderId: "snd_abc123",
  kbId: kb.knowledgeBase.id,
  title: "Return Policy",
  content: "Our return policy allows returns within 30 days of purchase...",
});

// 列出文档
const docs = await zavu.senders.agent.knowledgeBases.documents.list({
  senderId: "snd_abc123",
  kbId: kb.knowledgeBase.id,
});

Monitoring

监控

typescript

// Get agent stats
const stats = await zavu.senders.agent.stats({ senderId: "snd_abc123" });
console.log(`Invocations: ${stats.totalInvocations}`);
console.log(`Tokens: ${stats.totalTokensUsed}`);
console.log(`Cost: $${stats.totalCost}`);

// List executions
const executions = await zavu.senders.agent.executions.list({
  senderId: "snd_abc123",
  status: "error",
  limit: 20,
});
for (const exec of executions.items) {
  console.log(exec.id, exec.status, exec.errorMessage);
}

typescript

// 获取Agent统计数据
const stats = await zavu.senders.agent.stats({ senderId: "snd_abc123" });
console.log(`Invocations: ${stats.totalInvocations}`);
console.log(`Tokens: ${stats.totalTokensUsed}`);
console.log(`Cost: $${stats.totalCost}`);

// 列出执行记录
const executions = await zavu.senders.agent.executions.list({
  senderId: "snd_abc123",
  status: "error",
  limit: 20,
});
for (const exec of executions.items) {
  console.log(exec.id, exec.status, exec.errorMessage);
}

Execution Statuses

执行状态

Status	Description
`success`	Agent generated response successfully
`error`	Execution failed (LLM error, tool error, etc.)
`filtered`	Response blocked by safety filters
`rate_limited`	Provider rate limit exceeded
`balance_insufficient`	Account balance too low to process

状态	描述
`success`	Agent成功生成响应
`error`	执行失败（LLM错误、工具错误等）
`filtered`	响应被安全过滤器拦截
`rate_limited`	超出服务商速率限制
`balance_insufficient`	账户余额不足，无法处理

Delete Agent

删除Agent

typescript

await zavu.senders.agent.delete({ senderId: "snd_abc123" });

typescript

await zavu.senders.agent.delete({ senderId: "snd_abc123" });

Constraints

限制条件

One agent per sender
System prompt: max 10,000 characters
Context window: 1-50 messages
Temperature: 0-2
Max tokens: 1-4,096
Tool name: max 100 characters
Tool description: max 500 characters
Document content: max 100,000 characters
Knowledge base name: max 100 characters
Provider
```
zavu
```
doesn't require an API key (uses Zavu-hosted models)
All other providers require your own API key

每个发送方只能拥有一个Agent
系统提示词：最大10,000字符
上下文窗口：1-50条消息
温度参数：0-2
最大Token数：1-4,096
工具名称：最大100字符
工具描述：最大500字符
文档内容：最大100,000字符
知识库名称：最大100字符
服务商
```
zavu
```
无需API密钥（使用Zavu托管模型）
其他所有服务商均需自备API密钥