Metadata-Version: 2.4
Name: agentcore-sdk-agentrun-compat
Version: 0.1.0
Summary: Compatibility SDK for migrating AgentRun 0.0.53 applications to AgentCore
Author: AgentCore Team
License-Expression: Apache-2.0
Project-URL: Documentation, https://www.alibabacloud.com/help/en/agentcore/agentcore-product-overview
Keywords: agentcore,agentrun,compatibility,migration,alibaba-cloud
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentcore-sdk-agentrun-compat-core[credentials,mcp]<0.2,>=0.1.0
Provides-Extra: server
Requires-Dist: agentcore-sdk-agentrun-compat-core[server]<0.2,>=0.1.0; extra == "server"
Provides-Extra: mcp
Requires-Dist: agentcore-sdk-agentrun-compat-core[mcp]<0.2,>=0.1.0; extra == "mcp"
Dynamic: license-file

# 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:

```bash
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:

```bash
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:

```python
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:

```bash
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.
