# 启动和停止智能体 (/zh-CN/ai/build/start-stop-agent)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

本文介绍如何通过 Agora Agents SDK 或对话式 AI 引擎 RESTful API 启动和停止一个智能体。

## 前提条件 [#前提条件]

开始前，请确保你已经准备好：

使用 Agora CLI 创建项目，开启 RTC 和对话式 AI 引擎，检查项目状态，并导出本地凭据：

```bash
agora login --region cn
agora project create <project-name> --feature rtc --feature convoai --rtm-data-center CN
agora project use <project-name>
agora project doctor --feature convoai
agora project env --format shell --with-secrets
```

你还需要准备一个能够加入声网 RTC 频道的客户端应用，例如已完成基础[实时音视频互动](../../realtime-media/rtc/get-started/quick-start.mdx)的应用。

## 安装 SDK [#安装-sdk]

如果你使用 Agents SDK 启动和停止智能体，请选择你的开发语言并安装对应 SDK。

```bash tab="Python SDK" tabGroup="agent-sdk-language"
pip install agora-agents
```

```bash tab="TypeScript SDK" tabGroup="agent-sdk-language"
npm install agora-agents
```

```bash tab="Go SDK" tabGroup="agent-sdk-language"
go get github.com/AgoraIO/agora-agents-go/v2@v2.0.0
```

## 实现方式 [#实现方式]

### 启动智能体 [#启动智能体]

调用 SDK 的 `start()` 方法或 RESTful API 的 `join` 接口即可创建一个智能体实例，并让它加入指定频道。你需要传入频道名、智能体 UID、远端用户 UID 和模型配置；使用 SDK 且传入 App Certificate 时，SDK 会自动生成所需鉴权。

以下示例使用声网中国区推荐的级联链路配置：凤鸣 ASR、通义千问 LLM 和 MiniMax TTS。如需切换模型，请参考对应的模型文档调整 ASR、LLM 和 TTS 配置。

<Tabs defaultValue="go" groupId="agent-sdk-language" persist>
<TabsList>
  <TabsTrigger value="go">Go SDK</TabsTrigger>
  <TabsTrigger value="typescript">TypeScript SDK</TabsTrigger>
  <TabsTrigger value="python">Python SDK</TabsTrigger>
  <TabsTrigger value="rest-api">REST API</TabsTrigger>
</TabsList>

<TabsContent value="go">

```go
package main

import (
    "context"
    "log"

    Agora "github.com/AgoraIO/agora-agents-go/v2"
    agentkit "github.com/AgoraIO/agora-agents-go/v2/agentkit/cn"
    vendors "github.com/AgoraIO/agora-agents-go/v2/agentkit/cn/vendors"
)

func main() {
    ctx := context.Background()

    client := agentkit.NewAgoraClient(agentkit.ClientOptions{
        AppID:          "<your_app_id>",
        AppCertificate: "<your_app_certificate>",
    })

    agent := agentkit.NewAgent(client,
        agentkit.WithName("support-assistant"),
    ).WithStt(
        vendors.NewFengmingSTT(),
    ).WithLlm(
        vendors.NewAliyun(vendors.AliyunOptions{
            BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
            Model:   "qwen-plus",
            APIKey:  "<your_llm_api_key>",
            SystemMessages: []map[string]interface{}{
                {"role": "system", "content": "You are a helpful chatbot."},
            },
            GreetingMessage: "你好，有什么可以帮你？",
            FailureMessage:  "抱歉，我暂时无法回答这个问题。",
            MaxHistory:      Agora.Int(10),
        }),
    ).WithTts(
        vendors.NewMiniMaxTTS(vendors.MiniMaxTTSOptions{
            Key:   "<your_tts_api_key>",
            Model: "speech-01-turbo",
            VoiceSetting: &vendors.MiniMaxVoiceSetting{
                VoiceID: "female-shaonv",
            },
        }),
    )

    session := agent.CreateSession(agentkit.CreateSessionOptions{
        Channel:     "<your_channel_name>",
        AgentUID:    "0",
        RemoteUIDs:  []string{"1002"},
        IdleTimeout: Agora.Int(120),
    })

    agentID, err := session.Start(ctx)
    if err != nil {
        log.Fatal(err)
    }
    log.Println("Agent started:", agentID)
}
```

</TabsContent>

<TabsContent value="typescript">

```typescript
import {
  Agent,
  AgoraClient,
  AliyunLLM,
  Area,
  FengmingSTT,
  MiniMaxCNTTS,
} from 'agora-agents';

const client = new AgoraClient({
  area: Area.CN,
  appId: '<your_app_id>',
  appCertificate: '<your_app_certificate>',
});

const agent = new Agent({ client })
  .withStt(new FengmingSTT())
  .withLlm(new AliyunLLM({
    url: 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions',
    model: 'qwen-plus',
    apiKey: '<your_llm_api_key>',
    systemMessages: [
      { role: 'system', content: 'You are a helpful chatbot.' },
    ],
    greetingMessage: '你好，有什么可以帮你？',
    failureMessage: '抱歉，我暂时无法回答这个问题。',
    maxHistory: 10,
  }))
  .withTts(new MiniMaxCNTTS({
    key: '<your_tts_api_key>',
    model: 'speech-01-turbo',
    voiceSetting: { voice_id: 'female-shaonv' },
  }));

const session = agent.createSession({
  name: 'support-assistant',
  channel: '<your_channel_name>',
  agentUid: '0',
  remoteUids: ['1002'],
  idleTimeout: 120,
});

const agentId = await session.start();
console.log('Agent started:', agentId);
```

</TabsContent>

<TabsContent value="python">

```python
from agora_agent import (
    Agent,
    Agora,
    AliyunLLM,
    Area,
    FengmingSTT,
    MiniMaxCNTTS,
)

client = Agora(
    area=Area.CN,
    app_id='<your_app_id>',
    app_certificate='<your_app_certificate>',
)

agent = (
    Agent(client=client)
    .with_stt(FengmingSTT())
    .with_llm(AliyunLLM(
        base_url='https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions',
        model='qwen-plus',
        api_key='<your_llm_api_key>',
        system_messages=[
            {'role': 'system', 'content': 'You are a helpful chatbot.'},
        ],
        greeting_message='你好，有什么可以帮你？',
        failure_message='抱歉，我暂时无法回答这个问题。',
        max_history=10,
    ))
    .with_tts(MiniMaxCNTTS(
        key='<your_tts_api_key>',
        model='speech-01-turbo',
        voice_id='female-shaonv',
    ))
)

session = agent.create_session(
    name='support-assistant',
    channel='<your_channel_name>',
    agent_uid='0',
    remote_uids=['1002'],
    idle_timeout=120,
)

agent_id = session.start()
print('Agent started:', agent_id)
```

</TabsContent>

<TabsContent value="rest-api">

```bash
curl --request POST \
  --url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/join \
  --header 'Authorization: Basic <your_base64_encoded_credentials>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "support-assistant",
    "properties": {
      "channel": "<your_channel_name>",
      "token": "<your_rtc_token>",
      "agent_rtc_uid": "0",
      "remote_rtc_uids": ["1002"],
      "enable_string_uid": false,
      "idle_timeout": 120,
      "llm": {
        "vendor": "aliyun",
        "url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
        "api_key": "<your_aliyun_api_key>",
        "system_messages": [
          {
            "role": "system",
            "content": "You are a helpful chatbot."
          }
        ],
        "greeting_message": "你好，有什么可以帮你？",
        "failure_message": "抱歉，我暂时无法回答这个问题。",
        "max_history": 10,
        "params": {
          "model": "qwen-plus"
        }
      },
      "asr": {
        "language": "zh-CN",
        "vendor": "fengming"
      },
      "tts": {
        "vendor": "minimax",
        "params": {
          "group_id": "<your_minimax_group_id>",
          "key": "<your_tts_api_key>",
          "model": "speech-01-turbo",
          "voice_setting": {
            "voice_id": "female-shaonv",
            "speed": 1,
            "vol": 1,
            "pitch": 0
          },
          "audio_setting": {
            "sample_rate": 16000
          }
        }
      }
    }
  }'
```

如果通过 REST API 创建智能体，请求成功时返回 `200` 状态码，响应体如下：

```json
{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "create_ts": 1737111452,
  "status": "RUNNING"
}
```

</TabsContent>
</Tabs>

### 停止智能体 [#停止智能体]

当用户结束会话时，你的业务后端应调用 SDK 的 `stop()` 方法或 RESTful API 的 `leave` 接口，让智能体离开频道：

<Tabs defaultValue="go" groupId="agent-sdk-language" persist>
<TabsList>
  <TabsTrigger value="go">Go SDK</TabsTrigger>
  <TabsTrigger value="typescript">TypeScript SDK</TabsTrigger>
  <TabsTrigger value="python">Python SDK</TabsTrigger>
  <TabsTrigger value="rest-api">REST API</TabsTrigger>
</TabsList>

<TabsContent value="go">

```go
if err := session.Stop(ctx); err != nil {
    log.Fatal(err)
}
```

</TabsContent>

<TabsContent value="typescript">

```typescript
await session.stop();
```

</TabsContent>

<TabsContent value="python">

```python
session.stop()
```

</TabsContent>

<TabsContent value="rest-api">

```bash
curl --request POST \
  --url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/leave \
  --header 'Authorization: Basic <your_base64_encoded_credentials>' \
  --data '{}'
```

如果通过 REST API 停止智能体，请求成功时返回 `200` 状态码和空 JSON 对象：

```json
// 200 OK
{}
```

</TabsContent>
</Tabs>

## API 参考 [#api-参考]

- [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)
- [POST 停止对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/leave)
- [POST 更新智能体配置](/zh-CN/api-reference/api-ref/conversational-ai/update)
- [GET 查询智能体状态](/zh-CN/api-reference/api-ref/conversational-ai/query)
- [GET 获取智能体列表](/zh-CN/api-reference/api-ref/conversational-ai/list)