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. Initial release validation builds and installs both distributions on Python 3.10. Python 3.12 can be added to the validation matrix later without publishing another wheel, because both distributions are py3-none-any.

For applications that use AgentRunServer, install the server dependencies:

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

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.