AgentCore SDK 高代码协作使用指南

安装依赖

以下示例使用 Python 3.11 及以上版本，通过 LangChain 构建 Agent，通过 AgentCoreServer 提供 HTTP 服务。

python -m pip install \
  "alibabacloud-agentcore-sdk[server,langchain]==0.1.1" \
  "alibabacloud-agentcore-collaboration==0.1.1"

协作扩展包需要单独安装，常用能力通过 core.collaboration 访问。已发布版本请参见 PyPI。

创建 Agent 服务

将以下代码保存为 app.py。将模型连接、模型名称和业务提示词替换为您的配置。

import logging

from langchain.agents import create_agent
from agentcore import AsyncAgentCore
from agentcore.integrations.langchain import (
    AgentCoreConverter,
    model,
    skill_tools,
    tools,
)
from agentcore.server import AgentCoreServer, AgentRequest

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("collaboration_worker")
core = AsyncAgentCore.auto()
agent = None


async def startup():
    global agent
    try:
        worker = core.collaboration.worker()
        agent = create_agent(
            model=model("my-model-connection", model_name="qwen3.8-max"),
            system_prompt=worker.compose_prompt(
                "你是业务助手。回答用户问题，并使用工具完成分配的工作。"
            ),
            tools=[
                *tools(worker.tools()),
                *skill_tools(worker.skills()),
            ],
        )
    except Exception:
        logger.exception("worker.startup.failed")
        await core.aclose()
        raise


server = AgentCoreServer(
    startup=startup,
    shutdown=core.aclose,
    readiness=lambda: agent is not None,
)


@server.invoke
async def invoke(request: AgentRequest, _context):
    if agent is None:
        raise RuntimeError("Agent is not initialized")

    # 本例处理当前的一条文本输入，不维护服务端聊天历史。
    message = request.messages[-1] if request.messages else None
    if message is None or not isinstance(message.content, str):
        raise ValueError("Expected a text message")

    # 每次执行创建一个转换器，保留文本、工具调用和结果事件。
    async for event in AgentCoreConverter().stream(
        agent.astream_events(
            {"messages": [{"role": "user", "content": message.content}]},
            version="v2",
        )
    ):
        yield event

启动服务：

uvicorn app:server --host 0.0.0.0 --port 9000

安装依赖

以下 LangChain 示例建议使用 Node.js 22.22 及以上版本。

在应用目录安装依赖。已有项目请确认 package.json 包含 "type": "module"；新项目可先执行 npm init -y。

npm pkg set type=module
npm install alibabacloud-agentcore-sdk@0.1.2 \
  alibabacloud-agentcore-collaboration@0.1.2
npm install langchain@^1 @langchain/core@^1 @langchain/langgraph@^1 \
  @langchain/openai@^1 @langchain/anthropic@^1 zod@^4
npm install --save-dev tsx typescript @types/node

已发布版本请参见 npm。

创建 Agent 服务

将以下代码保存为 app.ts。将模型连接、模型名称和业务提示词替换为您的配置。

import { createAgent } from 'langchain';
import { AgentCore } from 'alibabacloud-agentcore-sdk';
import { AgentCoreServer } from 'alibabacloud-agentcore-sdk/server';
import {
  model, tools, AgentCoreConverter,
} from 'alibabacloud-agentcore-sdk/integrations/langchain';
import { skillTools } from 'alibabacloud-agentcore-sdk/skill';

const core = AgentCore.auto({ logger: console });

async function buildAgent() {
  const worker = await core.collaboration.worker();
  const client = await core.model('my-model-connection', {
    model: 'qwen3.8-max',
  });
  return createAgent({
    model: await model(client),
    systemPrompt: worker.composePrompt(
      '你是业务助手。回答用户问题，并使用工具完成分配的工作。',
    ),
    tools: tools([
      ...worker.tools(),
      ...skillTools(await worker.skills()),
    ]),
  });
}

let agent: Awaited<ReturnType<typeof buildAgent>> | undefined;
const server = new AgentCoreServer({
  logger: console,
  startup: async () => {
    try {
      agent = await buildAgent();
    } catch (error) {
      console.error('worker.startup.failed', error);
      await core.close();
      throw error;
    }
  },
  shutdown: () => core.close(),
  readiness: () => agent !== undefined,
  invoke: async function* (request) {
    if (!agent) throw new Error('Agent is not initialized');

    // 本例处理当前的一条文本输入，不维护服务端聊天历史。
    const content = request.messages.at(-1)?.content;
    if (typeof content !== 'string') {
      throw new Error('Expected a text message');
    }

    // 转换器属于本次执行，不在并发请求之间共享。
    const converter = new AgentCoreConverter();
    for await (const event of agent.streamEvents(
      { messages: [{ role: 'user', content }] },
      { version: 'v2', signal: request.signal },
    )) {
      yield* converter.convert(event);
    }
  },
});

await server.start({ port: 9000, hostname: '0.0.0.0' });
for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    void server.close().catch(error => {
      console.error(error);
      process.exitCode = 1;
    });
  });
}

启动服务：

npx tsx app.ts

镜像使用该启动命令时，需包含 tsx。如果构建时排除了开发依赖，请先将 TypeScript 编译为 JavaScript，再使用 node 启动编译产物。

安装依赖

使用 JDK 17 及以上版本、Maven 3.9 及以上版本。以下示例通过 LangChain4j 构建 Agent，通过 AgentCoreServer 提供 HTTP 服务。

Java 协作模块单独发布。示例使用基础 SDK、服务端和 LangChain4j 模块 0.1.3，独立协作模块 0.1.0，均可从 Maven Central 获取。

在应用目录创建 pom.xml：

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>collaboration-worker</artifactId>
  <version>1.0.0</version>
  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <agentcore.version>0.1.3</agentcore.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>io.github.ai-agentcore</groupId>
      <artifactId>agentcore-sdk</artifactId>
      <version>${agentcore.version}</version>
    </dependency>
    <dependency>
      <groupId>io.github.ai-agentcore</groupId>
      <artifactId>agentcore-sdk-server</artifactId>
      <version>${agentcore.version}</version>
    </dependency>
    <dependency>
      <groupId>io.github.ai-agentcore</groupId>
      <artifactId>agentcore-sdk-langchain4j</artifactId>
      <version>${agentcore.version}</version>
    </dependency>
    <dependency>
      <groupId>io.github.ai-agentcore</groupId>
      <artifactId>agentcore-collaboration</artifactId>
      <version>0.1.0</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>2.0.17</version>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.14.0</version>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.5.1</version>
        <configuration>
          <mainClass>example.CollaborationApp</mainClass>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

创建 Agent 服务

将以下代码保存为 src/main/java/example/CollaborationApp.java。将模型连接、模型名称和业务提示词替换为实际配置。本例在 AgentCore 托管环境中执行，无需在代码中填写平台访问密钥。

package example;

import dev.langchain4j.invocation.InvocationParameters;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.service.TokenStream;
import dev.langchain4j.service.UserMessage;
import io.agentcore.AgentCore;
import io.agentcore.Json;
import io.agentcore.collaboration.Collaboration;
import io.agentcore.collaboration.CollaborationContext;
import io.agentcore.langchain4j.AgentCoreLangChain4j;
import io.agentcore.langchain4j.LangChain4jEvents;
import io.agentcore.server.AgentCoreServer;
import io.agentcore.skill.Skill;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Map;

public class CollaborationApp {
    public interface Assistant {
        TokenStream chat(@UserMessage String input, InvocationParameters parameters);
    }


    public static void main(String[ ] args) throws Exception {

        var workspace = Path.of(
            System.getenv().getOrDefault("AGENT_WORKSPACE", ".")
        ).toAbsolutePath().normalize();
        Files.createDirectories(workspace);

        try (var core = AgentCore.auto();
             var collaboration = Collaboration.auto(core, workspace)) {
            // 在应用启动时解析模型、注册工具，不在请求处理线程上阻塞初始化。
            var model = AgentCoreLangChain4j.streamingModel(
                core.model("my-model-connection", "qwen3.8-max").block()
            );
            var toolList = new ArrayList<>(collaboration.tools().block());
            toolList.addAll(Skill.tools(collaboration.skills().block(), workspace));

            var assistant = AiServices.builder(Assistant.class)
                .streamingChatModel(model)
                .systemMessageProvider(id -> collaboration.composePrompt(
                    "你是业务助手。回答用户问题，并使用工具完成分配的工作。"
                ))
                .tools(AgentCoreLangChain4j.tools(toolList))
                .build();

            try (var server = new AgentCoreServer(request -> {
                // 本例处理当前一条文本输入，不维护服务端聊天历史。
                if (request.messages().isEmpty()) {
                    throw new IllegalArgumentException("Expected a text message");
                }
                var message = request.messages().get(request.messages().size() - 1);
                var input = Json.text(message.get("content"), "message content");

                // 上下文来自实际平台请求，每次调用独立传递，不放入共享 Agent。
                var context = CollaborationContext.fromHeaders(request.headers());
                Map<String, Object> metadata = context == null
                    ? Map.of() : Map.of(CollaborationContext.KEY, context);
                var parameters = InvocationParameters.from(metadata);

                // 保留文本、工具调用、工具结果以及消息边界。
                return LangChain4jEvents.from(() -> assistant.chat(input, parameters));
            }).start(9000)) {
                Runtime.getRuntime().addShutdownHook(new Thread(server::close));
                server.await();
            }
        }
    }
}

启动服务：

mvn compile exec:java

此命令需要镜像包含 Maven；也可以使用应用已有的构建方式打包后启动，但应确保全部运行时依赖都包含在镜像中。

Java 的默认 AG-UI 路径是 /agui，OpenAI Chat Completions 路径是 /openai/v1/chat/completions，两者均监听 9000 端口。平台配置需与实际服务一致，不要将 Python／Node.js 的 /ag-ui/agent 路径直接套到本示例。

接入其他 Java 框架

协作提示词、工具和 Skill 不限定 LangChain4j。已有 Spring AI 或 AgentScope Java 应用可保留原框架，只替换工具注册及请求上下文的传递方式：

表中的 metadata 与完整示例相同：以 CollaborationContext.KEY 为键，传入从真实平台请求头解析的上下文；没有协作上下文时使用空映射。AgentScope Java 的 sessionId 使用应用自身的会话标识。

工具在初始化时注册，请求上下文在每次执行时传递。无需为了协作而在每次请求重建 Agent，也不要把某次请求的上下文保存在共享 Agent 字段中。流式输出分别使用 LangChain4jEvents、SpringAIEvents 或 AgentScopeEvents，以保留工具调用和消息边界。

其他框架和已有业务资源的用法，请参见 Java SDK 使用指南。

部署应用

将应用和依赖构建到镜像中，在 AgentCore 创建或更新高代码 Agent。上述示例使用以下配置。

AgentCoreServer 默认提供上述两种协议。平台配置的协议、路径和端口需与应用一致。需要展示工具调用、结果和执行过程时，建议选择 AG-UI。

加入团队

在平台创建或选择团队，将该高代码 Agent 添加为 Worker。团队配置由平台管理，无需在代码或提示词中写入团队成员列表。

验证任务执行

1. 在团队会话中向 Worker 发送普通问候，确认它能正常回复。

2. 询问“你属于哪个团队，团队里有哪些成员？”，确认它能获取团队信息。

3. 通过 Leader 创建任务，并为该 Worker 分配一个范围明确的子任务，例如整理一份简短说明并提交结果。

4. 查看 Worker 是否接单、执行工作并提交结果。任务要求文件时，检查结果中是否包含交付文件。

5. 在任务视图中确认结果已提交，继续完成评审；如需返修，通过团队流程发起修订。

Python

from langchain.agents import create_agent
from agentcore import AsyncAgentCore
from agentcore.integrations.langchain import AgentCoreConverter, skill_tools, tools

# 在应用初始化时执行一次。
core = AsyncAgentCore.auto()
worker = core.collaboration.worker()
agent = create_agent(
    model=business_model,
    system_prompt=worker.compose_prompt(business_prompt),
    tools=[
        *business_tools,
        *tools(worker.tools()),
        *skill_tools(worker.skills()),
    ],
)


# 在已有 HTTP 请求处理函数中调用，并消费返回的事件。
async def stream_agent(headers, messages):
    with worker.request_context(headers):
        async for event in AgentCoreConverter().stream(
            agent.astream_events({"messages": messages}, version="v2")
        ):
            yield event

headers 使用实际入站请求头，例如 FastAPI 的 dict(request.headers)；messages 使用应用已经转换好的 LangChain 消息。现有服务消费 stream_agent() 的输出，并按原有协议写入响应。应用退出时调用 await core.aclose()。

Node.js

import { createAgent } from 'langchain';
import { AgentCore } from 'alibabacloud-agentcore-sdk';
import {
  tools, AgentCoreConverter,
} from 'alibabacloud-agentcore-sdk/integrations/langchain';
import { skillTools } from 'alibabacloud-agentcore-sdk/skill';

// 在应用初始化时执行一次。
const core = AgentCore.auto({ logger: console });
const worker = await core.collaboration.worker();
const agent = createAgent({
  model: businessModel,
  systemPrompt: worker.composePrompt(businessPrompt),
  tools: [
    ...businessTools,
    ...tools([
      ...worker.tools(),
      ...skillTools(await worker.skills()),
    ]),
  ],
});

type AgentInput = Parameters<typeof agent.invoke>[0];

// 在已有 HTTP 请求处理函数中调用。
async function streamAgent(
  headers: Record<string, string>,
  input: AgentInput,
  signal: AbortSignal,
  emit: (event: unknown) => Promise<void>,
) {
  await worker.requestContext(headers, async () => {
    const converter = new AgentCoreConverter();
    for await (const raw of agent.streamEvents(
      input, { version: 'v2', signal },
    )) {
      for (const event of converter.convert(raw)) await emit(event);
    }
  });
}

headers 是实际入站请求头的字符串映射，input 是原有 Agent 输入，signal 在客户端断开时取消，emit 由现有服务实现。应用退出时调用 await core.close()。

Java

Java 可以复用前文创建的 LangChain4j Assistant，由现有 HTTP 服务调用以下方法，无需启动 AgentCoreServer：

import dev.langchain4j.invocation.InvocationParameters;
import example.CollaborationApp.Assistant;
import io.agentcore.collaboration.CollaborationContext;
import io.agentcore.event.AgentEvent;
import io.agentcore.langchain4j.LangChain4jEvents;
import java.util.Map;
import reactor.core.publisher.Flux;

// 将此方法放在已有的 Java 服务类中。
public static Flux<AgentEvent> streamAgent(
        Assistant assistant, Map<String, String> headers, String input) {
    return Flux.defer(() -> {
        var context = CollaborationContext.fromHeaders(headers);
        Map<String, Object> metadata = context == null
            ? Map.of() : Map.of(CollaborationContext.KEY, context);
        var parameters = InvocationParameters.from(metadata);
        return LangChain4jEvents.from(() -> assistant.chat(input, parameters));
    });
}

headers 来自已验证的平台入口，input 是应用提取的本轮文本输入。现有服务将返回的 Flux<AgentEvent> 转成对应协议的响应，并在客户端断开时取消订阅；不要为输出结果而自行开启一个脱离请求生命周期的订阅。协作对象和 Core 由应用初始化并在退出时关闭。

Spring AI 和 AgentScope Java 使用前文表格中的原生调用上下文；不需要再套用 Python／Node.js 的请求包装方法。

与现有请求处理逻辑衔接

• 保留原有入口鉴权。Python／Node.js 将平台请求头交给请求包装方法；Java 从实际请求头解析 CollaborationContext，再通过框架调用上下文传入。不要根据聊天正文自行生成协作上下文。

• 上述函数输出 SDK 的 AgentEvent，不是可直接写入 HTTP 响应的 SSE 文本。现有服务需将事件转换为配置的 AG-UI 或 OpenAI Chat Completions 响应，并保留流式心跳和断连取消处理；不能直接序列化 LangChain 原始事件作为协议响应。

• 流式结果要在请求包装范围内完整消费。Python 示例已把包装放在生成器内部；Node.js 示例在回调内迭代并输出，不要只返回生成器后在外部消费。

• 在平台填写自建服务实际提供的端口和协议路径。前文 9000 端口和默认路径属于 AgentCoreServer 示例，不要求自建服务采用相同配置。

这些代码用于接入现有请求处理函数，不会另行启动 HTTP 服务。若使用其他 Agent 框架，保留同样的请求上下文传递方式，并换用对应框架的工具和事件适配器。

接入后，原来的提示词会失效吗？

不会。compose_prompt() / composePrompt() 在原有提示词之后追加协作说明，不替换业务身份。业务工具和 Skill 也可以继续使用。

必须使用 AgentCoreServer 吗？

不必。已有 AG-UI 或 OpenAI Chat Completions 服务可以继续使用；完成平台开通、部署并加入团队后，仅进行消息交流无需引入协作 SDK。需要完整使用任务协调和团队合作功能时，再接入协作提示词、工具和 Skill。Python 使用 worker.request_context()、Node.js 使用 worker.requestContext() 包围完整执行；Java 将 CollaborationContext 放入框架原生调用上下文，本文 Java 示例已显式完成此步骤。Python／Node.js 的 AgentCoreServer 示例会自动绑定请求上下文。保留应用原有的入口鉴权、协议响应和断连取消处理。

为什么安装了协作包，Agent 仍不能执行任务？

依次检查：是否已开通协作、Agent 是否作为 Worker 加入团队、是否注册了协作 Prompt／Tools／Skills，以及是否已通过团队流程分配任务。只安装包不会自动完成这些配置。

未加入团队时，还能正常聊天吗？

可以。没有团队时，协作操作不可用，但不会因此单独禁用模型对话。前提是应用本身已经正常初始化。

为什么有最终回复，却看不到工具执行过程？

确认使用了对应框架的事件适配器，不要只拼接文本输出。Python／Node.js 使用 AgentCoreConverter；本文 Java 示例使用 LangChain4jEvents.from()。每次执行独立转换，保留工具调用、工具结果和消息边界；需要完整过程展示时，使用 AG-UI 协议。

提交结果后，为什么任务没有直接完成？

提交结果与评审通过是两个步骤。Worker 提交后，由 Leader 或平台流程继续评审。请以任务视图中的实际状态为准。

调用失败时，如何排查？

先检查应用日志和协作工具返回的错误信息，确认模型可用、团队配置正确、任务仍分配给当前 Worker。Python 示例已开启 logging，Node.js 示例使用 console 记录日志。不要记录访问凭证或敏感文件内容。

写操作超时后，先查看任务状态或结果，避免重复提交。无法定位时，保留发生时间、Agent 和任务标识及相关错误信息，联系技术支持。

如何升级协作能力？

协作包可以独立升级，但需保持与基础 SDK 的版本兼容。本文 Python 示例使用基础包／协作包 0.1.1，Node.js 示例使用基础包／协作包 0.1.2；Java 示例使用基础 SDK 及服务端、框架模块 0.1.3，独立协作模块 0.1.0。更新依赖后，重新构建并部署应用。