> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beeos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 5 分钟部署你的第一个智能体并调用它 —— TypeScript、Python、Go 或 curl。

本指南带你从零到一个能聊天的运行中智能体，通过 BeeOS 公开 OpenAPI
完成。同样的流程可对本地 `http://localhost:8095` 和生产
`https://openapi.beeos.ai`。

## 准备

* 一个 [beeos.ai](https://beeos.ai) 账户。
* 一个**用户 API Key**（`oag_…`），到 **Settings → API Keys** 创建。
  这是长期 bearer 凭证 —— 见[认证](/zh/authentication)了解作用域和轮换。

## 1. 安装 SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @beeos-ai/sdk
  ```

  ```bash go theme={null}
  go get github.com/beeos-ai/sdk-go
  ```

  ```bash python theme={null}
  python -m pip install beeos
  ```

  ```bash curl theme={null}
  # 不需要安装 —— 直接用 curl。
  ```
</CodeGroup>

<Note>
  已发布的 `@beeos-ai/sdk` 由 OpenAPI Generator（`typescript-fetch`）
  从 OpenAPI 契约自动生成。它导出一个 `Configuration` 值和每个 OpenAPI
  tag 一个 class —— `DeployApi`、`InstancesApi`、`AgentsApi`、`TasksApi`、
  `ConversationsApi`、`FilesApi`。**没有** `BeeOS` 顶层 client。
</Note>

## 2. 配置 client

<CodeGroup>
  ```typescript TypeScript theme={null}
  import {
    Configuration,
    DeployApi,
    InstancesApi,
    AgentsApi,
  } from "@beeos-ai/sdk";

  const config = new Configuration({
    basePath: "https://openapi.beeos.ai",
    headers: { Authorization: `Bearer ${process.env.BEEOS_API_KEY}` },
  });

  const deploy = new DeployApi(config);
  const instances = new InstancesApi(config);
  const agents = new AgentsApi(config);
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "os"

      beeos "github.com/beeos-ai/sdk-go"
  )

  func main() {
      cfg := beeos.NewConfiguration()
      cfg.Servers = beeos.ServerConfigurations{
          {URL: "https://openapi.beeos.ai"},
      }
      cfg.DefaultHeader["Authorization"] = "Bearer " + os.Getenv("BEEOS_API_KEY")

      client := beeos.NewAPIClient(cfg)
      ctx := context.Background()
      _ = client
      _ = ctx
      fmt.Println("client ready")
  }
  ```

  ```python Python theme={null}
  import os
  import beeos

  configuration = beeos.Configuration(
      host="https://openapi.beeos.ai",
      access_token=os.environ["BEEOS_API_KEY"],
  )

  client = beeos.ApiClient(configuration)
  deploy = beeos.sdk.DeployApi(client)
  instances = beeos.sdk.InstancesApi(client)
  agents = beeos.sdk.AgentsApi(client)
  ```

  ```bash curl theme={null}
  export BEEOS_API_KEY="oag_…"
  export BASE=https://openapi.beeos.ai
  ```
</CodeGroup>

<Tip>
  Python 用户建议安装官方稳定入口 `beeos`。完整的 OpenAPI 生成接口仍可通过
  `beeos.sdk` 使用，详见 [Python SDK](/zh/sdks/python)。
</Tip>

## 3. 查看部署目录

<CodeGroup>
  ```typescript TypeScript theme={null}
  const providers = await deploy.listProviders();
  console.log(providers.data?.map(p => `${p.meta?.id} — ${p.meta?.name}`));

  const regions = await deploy.listDeployRegions({ providerId: "default" });
  const models = await deploy.listDeployModels({ agentFramework: "beeos-claw" });
  ```

  ```go Go theme={null}
  providers, _, _ := client.DeployAPI.ListProviders(ctx).Execute()
  for _, p := range providers.GetData() {
      fmt.Printf("%s — %s\n", p.Meta.GetId(), p.Meta.GetName())
  }
  ```

  ```bash curl theme={null}
  curl -s "$BASE/api/v1/providers" \
    -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

  curl -s "$BASE/api/v1/deploy/regions?providerId=default" \
    -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'

  curl -s "$BASE/api/v1/deploy/models?agentFramework=beeos-claw" \
    -H "Authorization: Bearer $BEEOS_API_KEY" | jq '.data'
  ```
</CodeGroup>

## 4. 部署一个智能体实例

<CodeGroup>
  ```typescript TypeScript theme={null}
  const created = await instances.deployInstance({
    deployInstanceRequest: {
      name: "my-first-agent",
      agentFramework: "beeos-claw",
      modelPrimary: "gpt-4o",
    },
  });
  const instanceId = created.data!.id;
  console.log(`实例 ${instanceId} — 状态: ${created.data!.status}`);
  ```

  ```go Go theme={null}
  req := beeos.DeployInstanceRequest{
      Name:           "my-first-agent",
      AgentFramework: "beeos-claw",
      ModelPrimary:   "gpt-4o",
  }
  created, _, _ := client.InstancesAPI.DeployInstance(ctx).
      DeployInstanceRequest(req).Execute()
  fmt.Printf("实例 %s — 状态: %s\n", created.Data.GetId(), created.Data.GetStatus())
  ```

  ```bash curl theme={null}
  curl -s -X POST "$BASE/api/v1/instances" \
    -H "Authorization: Bearer $BEEOS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "my-first-agent",
      "agentFramework": "beeos-claw",
      "modelPrimary": "gpt-4o"
    }' | jq '.data'
  ```
</CodeGroup>

部署需要几秒钟。轮询 `GET /instances/{id}` 直到
`status === "running"`，或在 dashboard 上看。

## 5. 拿到智能体 ID

一个部署的实例托管一个或多个智能体。调用要用的是智能体 ID（实例可
以被替换而不破坏你的集成；智能体身份是稳定的）。

<CodeGroup>
  ```typescript TypeScript theme={null}
  const list = await agents.listAgents({ instanceId, limit: 20 });
  const agentId = list.data![0].id;
  console.log(`调用智能体 ${agentId}`);
  ```

  ```go Go theme={null}
  list, _, _ := client.AgentsAPI.ListAgents(ctx).
      InstanceId(instanceId).Limit(20).Execute()
  agentID := list.GetData()[0].GetId()
  ```

  ```bash curl theme={null}
  AGENT_ID=$(curl -s "$BASE/api/v1/agents?instanceId=$INSTANCE_ID&limit=20" \
    -H "Authorization: Bearer $BEEOS_API_KEY" | jq -r '.data[0].id')
  echo "调用智能体 $AGENT_ID"
  ```
</CodeGroup>

## 6. 调用智能体

阻塞调用在智能体完成回复后返回一个 JSON 载荷。长 prompt 见
[流式](/zh/guides/streaming)。

<CodeGroup>
  ```typescript TypeScript theme={null}
  const reply = await agents.invokeAgent({
    agentId,
    invokeAgentRequest: {
      message: "你好 —— 你能做什么？",
    },
  });
  console.log("回复:", reply.data?.text);
  console.log("Channel:", reply.data?.context_id);
  ```

  ```go Go theme={null}
  reply, _, _ := client.AgentsAPI.InvokeAgent(ctx, agentID).
      InvokeAgentRequest(beeos.InvokeAgentRequest{
          Message: "你好 —— 你能做什么？",
      }).Execute()
  fmt.Println("回复:", reply.GetData().GetText())
  ```

  ```bash curl theme={null}
  curl -s -X POST "$BASE/api/v1/agents/$AGENT_ID/invoke" \
    -H "Authorization: Bearer $BEEOS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"message": "你好 —— 你能做什么？"}' | jq '.data'
  ```
</CodeGroup>

### 流式变体

同一个端点设 `Accept: text/event-stream` 即可接收
`agent_reply_delta` 分块，最后由一个 `agent_reply` 关闭。SDK 不抽象
SSE —— 回落到 `fetch` / `http.Client`。

```bash theme={null}
curl -N -X POST "$BASE/api/v1/agents/$AGENT_ID/invoke" \
  -H "Authorization: Bearer $BEEOS_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"message": "讲个短故事。"}'
```

## 6.5. invoke 调用会出现在哪里？

每次 `invoke` 都会创建一个短生命周期的 `protocol=openapi` **任务** 通道，
而不是会话。可以通过下面的命令查看：

```bash theme={null}
curl -s "$BASE/api/v1/agents/$AGENT_ID/tasks?state=all" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq
```

`GET /agents/{agentId}/conversations` 只返回你通过 `POST /conversations`
显式创建的长生命周期对话通道。`invoke` 之后立即调用该接口返回空列表
属于预期行为 —— 见 [调用智能体](/zh/guides/calling-agents) 指南，了解
何时该用 conversation 何时该用 invoke。

## 7. 清理

```bash theme={null}
curl -s -X DELETE "$BASE/api/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq
```

## 下一步去哪

<CardGroup cols={2}>
  <Card title="选择协议" icon="signs-post" href="/zh/guides/choosing-a-protocol">
    在 OpenAPI（本指南）、A2A、MCP 之间做出选择。
  </Card>

  <Card title="调用智能体" icon="message-bot" href="/zh/guides/calling-agents">
    幂等键、附件、任务、会话、错误处理。
  </Card>

  <Card title="Webhook" icon="webhook" href="/zh/guides/webhooks">
    HMAC 签名的终态回调 + 重试 + 审计日志。
  </Card>

  <Card title="A2A 协议" icon="arrows-rotate" href="/zh/a2a/overview">
    `a2a.beeos.ai` 上的 JSON-RPC + 智能体卡片。
  </Card>
</CardGroup>