Metadata-Version: 2.4
Name: agentcore-sdk-agentrun-compat
Version: 0.1.0.post1
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.1.0.post1
Provides-Extra: server
Requires-Dist: agentcore-sdk-agentrun-compat-core[server]==0.1.0.post1; extra == "server"
Provides-Extra: mcp
Requires-Dist: agentcore-sdk-agentrun-compat-core[mcp]==0.1.0.post1; extra == "mcp"
Provides-Extra: langchain
Requires-Dist: agentcore-sdk-agentrun-compat-core[langchain]==0.1.0.post1; extra == "langchain"
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. 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:

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

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

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

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

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

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

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