# 连接消息通道

检查部署环境支持的通道接入能力，为选定智能体创建 Slack 托管长连接（Socket Mode），并核查连接运行状态与实际消息收发。

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

```text
查询部署环境支持的通道接入能力
              │
              ▼
为目标智能体创建 Slack 托管流连接
              │
              ▼
读取连接状态直至 observed_state 为 connected
              │
              ▼
在 Slack 发送测试消息并核对智能体回复
```

(sdk-ai-studio-agent-ingress-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. 通过 [发现与选择智能体](发现与选择智能体.md#sdk-ai-studio-agents-s1) 获取目标智能体 ID（`AGENT_ID`）及所属工作区 ID（`AGENT_WORKSPACE_ID`），并通过 [查看模型后端与端点](../资源中心/管理模型后端.md) 确定运行模型（`AGENT_MODEL`）。
3. 按 [Slack 配置指南](../../../../guides/ai-studio/agents/manage-agents/im-connection/slack.md) 准备 Slack 应用凭据，并在受保护的环境变量中设置 **App ID**（`SLACK_APP_ID`）、**App-Level Token**（`SLACK_APP_TOKEN`）和 **Bot Token**（`SLACK_BOT_TOKEN`）。

(sdk-ai-studio-agent-ingress-create)=
## 检查能力并创建托管连接

先调用 `list_ingress_capabilities`（Go 为 `ListIngressCapabilities`）确认当前部署开放了 Slack `managed_stream` 接入模式，再调用 `create_ingress_connection`（Go 为 `CreateIngressConnection`）绑定智能体与 Slack 应用凭据。

:::::{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"],
)
service = client.agents(os.environ["WORKSPACE_ID"])

capabilities = service.list_ingress_capabilities()
if not any(
    item.provider == "slack"
    and item.channel_type == "slack_app"
    and "managed_stream" in item.receive_modes
    for item in capabilities.items
):
    raise SystemExit("Slack managed streams are not advertised on this deployment")

connection = service.create_ingress_connection(
    sdk.IngressConnectionCreateRequest(
        target=sdk.AgentTargetRef(
            kind="agent",
            workspace_id=os.environ["AGENT_WORKSPACE_ID"],
            id=os.environ["AGENT_ID"],
        ),
        provider="slack",
        channel_type="slack_app",
        receive_mode="managed_stream",
        agent_model=os.environ["AGENT_MODEL"],
        managed_stream=sdk.IngressManagedStreamConfig(
            app_id=os.environ["SLACK_APP_ID"],
            app_token=os.environ["SLACK_APP_TOKEN"],
            bot_token=os.environ["SLACK_BOT_TOKEN"],
        ),
    )
)
print("Connection:", connection.id, "Versions:", connection.association_version, connection.config_version)
print("State:", connection.desired_state, connection.observed_state, connection.last_error_code)
```

::::

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

```go
package main

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

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

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

	service := client.Agents(os.Getenv("WORKSPACE_ID"))
	capabilities, err := service.ListIngressCapabilities(ctx)
	if err != nil {
		log.Fatal(err)
	}
	supported := false
	for _, item := range capabilities.GetItems() {
		if item.GetProvider() == "slack" && item.GetChannelType() == "slack_app" {
			for _, mode := range item.GetReceiveModes() {
				if mode == "managed_stream" {
					supported = true
				}
			}
		}
	}
	if !supported {
		fmt.Println("Slack managed streams are not advertised on this deployment")
		return
	}

	connection, err := service.CreateIngressConnection(ctx, sdk.IngressConnectionCreateRequest{
		Target: &sdk.AgentTargetRef{
			Kind:        "agent",
			WorkspaceId: os.Getenv("AGENT_WORKSPACE_ID"),
			Id:          os.Getenv("AGENT_ID"),
		},
		Provider:    "slack",
		ChannelType: "slack_app",
		ReceiveMode: "managed_stream",
		AgentModel:  os.Getenv("AGENT_MODEL"),
		ManagedStream: &sdk.IngressManagedStreamConfig{
			AppID:    os.Getenv("SLACK_APP_ID"),
			AppToken: os.Getenv("SLACK_APP_TOKEN"),
			BotToken: os.Getenv("SLACK_BOT_TOKEN"),
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Connection:", connection.GetId(), "Versions:", connection.GetAssociationVersion(), connection.GetConfigVersion())
	fmt.Println("State:", connection.GetDesiredState(), connection.GetObservedState(), connection.GetLastErrorCode())
}
```

::::

:::::

保存返回的连接 `id`、`association_version` 与 `config_version`，后续更新或停用连接时需传入对应版本号执行乐观并发控制。

(sdk-ai-studio-agent-ingress-verify)=
## 确认连接状态与消息收发

Slack `managed_stream` 连接由平台接收器主动与 Slack 建立长连接。接续上例调用 `get_ingress_connection`（Go 为 `GetIngressConnection`）读取最新 `observed_state` 与 `last_error_code`：

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

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

```python
current = service.get_ingress_connection(connection.id)
print(current.desired_state, current.observed_state, current.last_error_code)
if current.observed_state in ("auth_failed", "config_invalid"):
    raise RuntimeError("Correct the Slack credentials or connection configuration")
if current.observed_state != "connected":
    print("Receiver is still connecting; check observed_state again before testing delivery")
```

::::

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

```go
current, err := service.GetIngressConnection(ctx, connection.GetId())
if err != nil {
	log.Fatal(err)
}
fmt.Println(current.GetDesiredState(), current.GetObservedState(), current.GetLastErrorCode())
if current.GetObservedState() == "auth_failed" || current.GetObservedState() == "config_invalid" {
	log.Fatal("correct the Slack credentials or connection configuration")
}
if current.GetObservedState() != "connected" {
	fmt.Println("Receiver is still connecting; check observed_state again before testing delivery")
}
```

::::

:::::

(sdk-ai-studio-agent-ingress-limit)=
## 限制和注意事项

- `observed_state` 为 `starting` 或 `reconnecting` 表示接收器正在建立或恢复连接；变为 `connected` 后，建议在 Slack 中向应用发送一条测试消息，并核查目标智能体的会话记录与实际回复。
- 更新连接配置或绑定关系时需携带最近一次读取的 `association_version` 与 `config_version`；出现版本冲突时重新读取最新连接对象后再提交。

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

- [测试通道配置](测试通道配置.md)
- [读取智能体会话](管理会话和消息.md#sdk-ai-studio-sessions-s1)
