AgentCore SDK for AgentRun Compatibility

agentcore-sdk-agentrun-compat is a compatibility SDK for users migrating Python applications from the original AgentRun SDK to AgentCore. It preserves the agentrun import namespace and forwards supported operations to the AgentCore implementation.

It is not the official AgentCore SDK. Its distribution name makes the migration purpose explicit, while existing application imports can remain unchanged.

Install

Remove the original AgentRun package before installing the compatibility SDK:

python -m pip uninstall -y agentrun-sdk
python -m pip install agentcore-sdk-agentrun-compat

The SDK requires Python 3.10 or newer. Release validation builds and installs both distributions in clean Python 3.10 and Python 3.12 containers. Both distributions are py3-none-any wheels.

For applications that use AgentRunServer, install the server dependencies:

python -m pip install "agentcore-sdk-agentrun-compat[server]"

For applications that use agentrun.integration.langchain, install the LangChain dependencies through the compatibility entry package:

python -m pip install "agentcore-sdk-agentrun-compat[langchain]"

If the application also uses AgentRunServer or AgentRunConverter, install the two extras together:

python -m pip install "agentcore-sdk-agentrun-compat[server,langchain]"

Existing LangChain imports can remain unchanged. ModelService, ToolResource, Skill, supported KnowledgeBase wrappers, and local AgentRun-compatible Tool objects are converted to LangChain objects through their existing integration functions. The original AgentRun ToolSet* service surface, ModelProxy, and Sandbox remain unsupported because AgentCore has no equivalent platform capability. AgentRunConverter is available from both the LangChain and LangGraph compatibility paths; the rest of the LangGraph adapter remains unsupported in this release.

The existing AgentRun-shaped calls remain the same:

from agentrun.integration.langchain import model, tool_resource

chat_model = model("orders-model", model="qwen-plus")
tools = tool_resource("orders-tools")
chat_model_with_tools = chat_model.bind_tools(tools)

Streaming LangChain/LangGraph events can continue to use the existing instance-based converter API:

from agentrun.integration.langchain import AgentRunConverter

converter = AgentRunConverter()
async for event in agent.astream_events(input_data, stream_mode="messages"):
    for item in converter.convert(event):
        yield item

This conversion layer is independent of any quick-create helper. It only turns the compatible AgentRun model and tool resources into LangChain objects.

The package automatically installs agentcore-sdk-agentrun-compat-core; users do not need to install the core wheel separately.

Keep existing imports

Typical AgentRun imports do not need to change:

from agentrun.agent_runtime import AgentRuntimeClient
from agentrun.agent_runtime.model import AgentRuntimeCreateInput
from agentrun.utils.config import Config

The SDK currently targets the public interface baseline of AgentRun SDK 0.0.53. The compatibility package version and agentrun.__version__ describe different things: the former versions this migration SDK, while the latter reports the AgentRun interface baseline being emulated.

Connect to AgentCore

Configure the AgentCore workspace and Alibaba Cloud credentials before running the application:

export AGENTCORE_WORKSPACE_ID="<workspace-id>"
export ALIBABA_CLOUD_ACCESS_KEY_ID="<access-key-id>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<access-key-secret>"

Optional settings include:

• AGENTCORE_ENDPOINT: AgentCore control-plane endpoint.
• AGENTCORE_REGION_ID: region used to derive the default endpoint.
• AGENTCORE_API_VERSION: AgentCore OpenAPI version sent by the SDK.
• ALIBABA_CLOUD_SECURITY_TOKEN: STS security token.

Legacy AgentRun credential variable names are accepted only as a migration aid and emit a deprecation warning. AgentRun control-plane endpoints are not reused; the SDK connects to AgentCore.

Migration boundary

The compatibility surface covers the AgentRun-style APIs that can be mapped to AgentCore, including Agent Runtime management, models, credentials, MCP, tools, toolsets, skills, SuperAgent resources, and the local server package. Some operations have platform-specific prerequisites or narrower input support. Capabilities that AgentCore does not provide are not simulated silently; the SDK reports an explicit unsupported-capability or migration error.

In particular, packaging and deployment inputs must follow AgentCore's artifact model. Existing business ZIP files and runtime state are deployment artifacts, not Python package installation sources. Store application artifacts in the location required by AgentCore and keep persistent application state in the storage service selected for the migrated workload.

Do not install this package together with agentrun-sdk, because both packages provide the same agentrun import namespace.