:AgentCore Python SDK User Guide

An Agent application usually connects to cloud models, external tools, and long-term memory at the same time. Maintaining a separate endpoint, credential, and session state for each capability quickly makes application code hard to maintain. This topic is the Python volume of AgentCore SDK Overview, which covers language selection, capability boundaries, and an overview of the preparations.

This topic covers two resource paths:

• Cloud resources — Also called platform resources. They are configured in your Workspace, your code calls them by name, and the examples run in the AgentCore managed application runtime environment.

• Custom resources — Your own models, MCP servers, and Skills that ship with your application. They do not need to be registered as platform resources, and your application provides the connection settings. For details, see "Connect custom resources".

Prerequisites

Install the SDK

Install the base SDK:

pip install alibabacloud-agentcore-sdk==0.1.1

Install the optional dependencies that you need for MCP, HTTP serving, credentials, or framework integrations. The following command uses LangChain as an example. For another framework, replace langchain with the corresponding optional dependency in the following table.

pip install "alibabacloud-agentcore-sdk[mcp,server,credentials,langchain]==0.1.1"

The examples in this topic use Python SDK 0.1.1. For later versions, see the alibabacloud-agentcore-sdk PyPI package page.

Create and manage Core

The cloud resource snippets in this topic run within the lifecycle of an existing core. Create Core in one of the following ways:

• Cloud resource examples use async with AsyncAgentCore.auto() as core. For the complete example, see "Call cloud models". The SDK gets the access configuration from the application runtime environment, so you do not need to put platform access keys in your application code.

• Custom resource examples construct Core directly with async with AsyncAgentCore() as core, and your application provides the connection settings. For details, see "Connect custom resources".

  Reuse one Core within the application lifecycle and close it when the application exits. (Recommended) Use an async context manager (async with AsyncAgentCore.auto() as core), or call await core.aclose(). Do not close a shared Core at the end of each HTTP request while other requests are still using it.

Call cloud models

Specify the model connection name and the model name in your code. The SDK looks up the model connection in the Workspace that the current Agent belongs to, so you do not need to construct the model endpoint yourself.

import asyncio
from agentcore import AsyncAgentCore

async def main():
    async with AsyncAgentCore.auto() as core:
        model = await core.model("my-model-connection", model="qwen3.8-max")
        response = await model.invoke(
            [{"role": "user", "content": "Describe Hangzhou in one sentence."}],
            temperature=0.2,
        )
        print(response["choices"][0]["message"]["content"])

asyncio.run(main())

async for chunk in model.stream([{"role": "user", "content": "Describe Hangzhou in one sentence."}]):
    for choice in chunk.get("choices", []):
        print(choice.get("delta", {}).get("content") or "", end="", flush=True)

Use MCP tools

The following snippet runs within the lifecycle of the core that you created in "Create and manage Core". Listing tools only discovers them; it does not run any tool.

mcp = await core.mcp("my-mcp")
available_tools = await mcp.list_tools()
for tool in available_tools:
    print(tool.name, tool.description, tool.parameters)

# Replace these with the tool name and parameters that the MCP server actually provides.
result = await mcp.call_tool("<tool-name>", {"<parameter-name>": "<parameter-value>"})

To let the model select and run tools, pass the tools to your Agent framework as shown in the "Build an Agent service with LangChain" example. A model call by itself does not run MCP tools. If an MCP server requires authentication, bind a credential to the client as described in "Bind a credential to an MCP server".

Use Skills

A Skill contains task instructions and optional supporting files or scripts. After you load a Skill, connect it to your Agent through a framework integration. For the complete integration, see the "Build an Agent service with LangChain" example.

skill = await core.skills.managed("my-skill", version="1.0.0")
print(skill.name, skill.version)

1.0.0 must be a version of the Skill that is in the Published state. If you omit the version, the platform resolves the default version. Specify a version explicitly when you need to keep the behavior of your application fixed.

Use memory

A MemoryStore saves and retrieves long-term memory. It is a different capability from the conversation history that you send to a model: after you retrieve memories, your application code or a framework integration must pass them to the model as reference information.

from agentcore.memory import MemoryScope

store = core.memory_store("my-memory")
await store.add_memories(
    scope=MemoryScope(user_id="example-user", session_id="example-session"),
    text="The user prefers short answers.",
)

result = await store.search_memories(
    "What response preferences does the user have?",
    scope=MemoryScope(user_id="example-user"),
    top_k=5,
)
for hit in result.memories:
    print(hit.memory.content.text)

Use credentials and MCP headers

credential = await core.credentials.get("my-api-key")
api_key = credential.value  # Pass this to the client that needs the credential. Do not print it.

header_credential = await core.credentials.get("my-mcp-header")
headers = header_credential.as_headers()

mcp = await core.mcp(
    "my-mcp",
    credential_name="my-mcp-header",
    headers={"x-business-id": "my-app"},
)

Connect custom resources

Your own models, MCP servers, and Skills that ship with your application do not need to be registered as platform resources. Your application provides the following settings, and the environment variables in the example are not configuration items that the SDK reads automatically.

import asyncio
import os
from agentcore import AsyncAgentCore

async def main():
    async with AsyncAgentCore() as core:
        model = core.direct_model(
            provider="openai",
            model=os.environ["CUSTOM_MODEL_NAME"],
            base_url=os.environ["CUSTOM_MODEL_BASE_URL"],
            api_key=os.environ["CUSTOM_MODEL_API_KEY"],
        )
        response = await model.invoke([{"role": "user", "content": "Hello"}])
        print(response["choices"][0]["message"]["content"])

        mcp = core.direct_mcp(url=os.environ["CUSTOM_MCP_URL"])
        print([tool.name for tool in await mcp.list_tools()])
        skills = await core.skills.local("./skills")
        print([skill.name for skill in skills])

asyncio.run(main())

When a directly connected MCP server requires authentication, provide headers through headers_provider. The stdio transport does not use HTTP headers.

Build an Agent service with LangChain

AgentCoreServer is not a prerequisite for calling cloud resources. You can use the model, MCP, Skill, memory, and credential interfaces in an existing web service or Agent executor, and AgentCoreServer only reuses its protocol encapsulation.

The following example connects a cloud model, an MCP server, and a Skill to LangChain and serves them through AgentCoreServer. Before you start, prepare my-model-connection, my-mcp, and my-skill, and install the framework dependencies described in "Install the SDK".

The example handles only the latest user text message and does not store conversation history. For multi-turn conversations, your application or framework must maintain the history and the checkpoints.

Save the following code as app.py:

import logging
from langchain.agents import create_agent
from langchain_core.messages import HumanMessage

from agentcore import AsyncAgentCore
from agentcore.integrations.langchain import AgentCoreConverter, model, skill_tools, tools
from agentcore.server import AgentCoreServer

logging.basicConfig(level=logging.INFO)
core = None
chat = None
agent = None

async def shutdown():
    try:
        if chat is not None:
            await chat.root_async_client.close()
            chat.root_client.close()
    finally:
        if core is not None:
            await core.aclose()

async def startup():
    global core, chat, agent
    core = AsyncAgentCore.auto()
    try:
        mcp = await core.mcp("my-mcp")
        skill = await core.skills.managed("my-skill")
        chat = model("my-model-connection", model_name="qwen3.8-max")
        agent = create_agent(
            model=chat,
            tools=[*tools(await mcp.list_tools()), *skill_tools([skill])],
            system_prompt="Use the tools to complete the request. Do not fabricate tool results.",
        )
    except Exception:
        logging.exception("Agent initialization failed")
        await shutdown()
        raise

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

@server.invoke
async def invoke(request, context):
    if not request.messages:
        raise ValueError("Provide a user message.")
    message = request.messages[-1]
    if message.role.value != "user" or not isinstance(message.content, str):
        raise ValueError("This example supports only user text messages.")
    events = agent.astream_events(
        {"messages": [HumanMessage(content=message.content)]},
        version="v2",
    )
    async for event in AgentCoreConverter().stream(events):
        yield event

Run the following start command in the application runtime environment:

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

The example is written for an OpenAI/v1 model connection, and the shutdown logic matches the LangChain OpenAI client in this example.

Deploy the Agent service

Package your application code and dependencies and deploy them to AgentCore. The application runtime environment must include the SDK and framework dependencies described in "Install the SDK". If you use a container image, install the dependencies when you build the image.

The port that you configure on the platform must match the port that your application listens on. The SDK does not upload code, build images, or deploy applications.

Call the Agent service

Replace https://<agent-endpoint> in the following examples with the actual access address of your application, and add the authentication information that your application requires. This address is the address of the Agent application, not the address of a model provider.

curl -N 'https://<agent-endpoint>/ag-ui/agent' \
  -H 'Content-Type: application/json' \
  -d '{
    "threadId": "example-thread-1",
    "runId": "example-run-1",
    "messages": [{"id": "message-1", "role": "user", "content": "List the available Skills and complete a demonstration as instructed."}],
    "state": {},
    "tools": [],
    "context": [],
    "forwardedProps": {}
  }'

curl -N 'https://<agent-endpoint>/openai/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "agentcore",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Other framework integrations

The following table is the complete reference for all supported frameworks, including the LangChain framework used in "Build an Agent service with LangChain". It lists the optional dependency, the framework integration entry point, and the memory integration entry point of each framework:

These framework entry points also provide execution event converters, and the input must be the complete event stream of the corresponding framework. LangChain and LangGraph use astream_events(version="v2").

The complete event trace of CrewAI is emitted after the run finishes instead of token by token in real time. Different frameworks have different event inputs and output timing, so do not reuse the event handling approach of another framework directly.

FAQ

References

• AgentCore SDK Overview: an overview of SDK capabilities, development language selection, and service protocol comparison.

• Manage Workspace: create and switch Workspaces. All resources in the examples in this topic belong to a Workspace.

• Manage Models: add a model connection and configure models in that connection.

• Manage MCP Servers: create and manage MCP servers for a Workspace.

• Manage Skill: create a Skill, enable it, and publish a version.

• Manage credentials: create an API key credential or an MCP header credential and grant it to your application.

• alibabacloud-agentcore-sdk PyPI package page: check the latest version of the Python SDK.

• AgentCore product page: learn about the positioning and core features of AgentCore.