# 发现与选择智能体

查询当前工作区可见的智能体目录卡片，确认对象类型、状态与可用操作，并记录后续调用所需的智能体 ID 与所属工作区 ID。

(sdk-ai-studio-agents-flow)=
## 任务流程

```text
工作区客户端
    │
    ▼
分页查询智能体目录卡片
    │
    ▼
核对类型（agent）、状态与可用操作
    │
    ▼
保存智能体 ID 与所属工作区 ID
```

(sdk-ai-studio-agents-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。

(sdk-ai-studio-agents-s1)=
## 查询智能体目录卡片

运行以下示例列出当前工作区前 20 条目录卡片，输出每条记录的对象类型、所属工作区 ID、智能体 ID、名称、状态和可用动作。需要读取后续页时，在查询选项中传入 `offset` 继续翻页，直到已读数量达到 `total` 或返回空列表。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace_id = os.environ["WORKSPACE_ID"]
page = client.agents(workspace_id).list_agent_catalog_cards(
    sdk.with_query_param("limit", "20"),
    sdk.with_query_param("offset", "0"),
)
print("total:", page.total, "limit:", page.limit, "offset:", page.offset)
for card in page.items:
    print(
        card.kind,
        card.workspace_id,
        card.id,
        card.name,
        card.status,
        list(card.actions),
    )
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	page, err := client.Agents(os.Getenv("WORKSPACE_ID")).ListAgentCatalogCards(
		context.Background(),
		sdk.WithQueryParam("limit", "20"),
		sdk.WithQueryParam("offset", "0"),
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("total:", page.GetTotal(), "limit:", page.GetLimit(), "offset:", page.GetOffset())
	for _, card := range page.GetItems() {
		fmt.Println(
			card.GetKind(),
			card.GetWorkspaceId(),
			card.GetId(),
			card.GetName(),
			card.GetStatus(),
			card.GetActions(),
		)
	}
}
```

::::

:::::

目录中可能同时包含单智能体（`agent`）与团队条目，也可能包含系统来源条目。单智能体调用与版本维护应选择 `kind` 为 `agent` 的条目，并同时记录其 `id` 与 `workspace_id`。

(sdk-ai-studio-agents-next)=
## 下一步

- [调用智能体与跟踪任务](调用智能体并跟踪任务.md#sdk-ai-studio-agent-task-send)
- [管理智能体版本](查看和切换智能体版本.md#sdk-ai-studio-agent-version-list)
- [连接消息通道](连接消息通道.md)
