Metadata-Version: 2.1
Name: agent_runtimes
Version: 1.0.25
Summary: Agent Runtimes
Project-URL: Homepage, https://github.com/datalayer/agent-runtimes
Project-URL: Documentation, https://agent-runtimes.datalayer.tech
Project-URL: Repository, https://github.com/datalayer/agent-runtimes
Project-URL: Issues, https://github.com/datalayer/agent-runtimes/issues
Project-URL: Changelog, https://github.com/datalayer/agent-runtimes/blob/main/CHANGELOG.md
License: BSD-3-Clause
License-File: LICENSE
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: agent-client-protocol>=0.7.1
Requires-Dist: agent-codemode
Requires-Dist: agent-skills
Requires-Dist: code-sandboxes
Requires-Dist: croniter>=6.0.0
Requires-Dist: datalayer-core>=1.1.52
Requires-Dist: fastapi<0.142.0,>=0.116.1
Requires-Dist: filelock>=3.20.3
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: jupyter-server<3,>=2.10
Requires-Dist: mcp<2,>=1.10.1
Requires-Dist: nbformat<6.0.0,>=5.10.0
Requires-Dist: opentelemetry-api<2.0.0,>=1.40.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.40.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0.0,>=1.40.0
Requires-Dist: opentelemetry-instrumentation<0.62,>=0.61b0
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.40.0
Requires-Dist: opentelemetry-semantic-conventions<0.62,>=0.61b0
Requires-Dist: pydantic-ai-slim[mcp]<3,>=2.21.0
Requires-Dist: pydantic-graph<3,>=2.21.0
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic[email]>=2.13.3
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: typer>=0.16.0
Requires-Dist: urllib3>=2.6.3
Provides-Extra: a2a
Requires-Dist: a2a-sdk[all]<0.4.0,>=0.3.0; extra == 'a2a'
Requires-Dist: fasta2a; extra == 'a2a'
Provides-Extra: agent-sudo
Requires-Dist: agent-sudo>=0.4.0rc14; extra == 'agent-sudo'
Provides-Extra: all
Requires-Dist: agent-runtimes[a2a,anthropic,aws,durable,google,logfire,memory,openai,ui]; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic<1.0.0,>=0.105.0; extra == 'anthropic'
Requires-Dist: pydantic-ai-slim[anthropic]<3,>=2.21.0; extra == 'anthropic'
Provides-Extra: aws
Requires-Dist: boto3<1.43.0,>=1.42.96; extra == 'aws'
Requires-Dist: pydantic-ai-slim[bedrock]<3,>=2.21.0; extra == 'aws'
Provides-Extra: chat
Requires-Dist: jupyter-nbmodel-client; extra == 'chat'
Requires-Dist: pillow; extra == 'chat'
Requires-Dist: prompt-toolkit>=3.0.0; extra == 'chat'
Requires-Dist: requests; extra == 'chat'
Requires-Dist: rich>=13.0.0; extra == 'chat'
Requires-Dist: textual; extra == 'chat'
Provides-Extra: cli
Requires-Dist: jupyter-nbmodel-client; extra == 'cli'
Requires-Dist: pillow; extra == 'cli'
Requires-Dist: prompt-toolkit>=3.0.0; extra == 'cli'
Requires-Dist: requests; extra == 'cli'
Requires-Dist: rich>=13.0.0; extra == 'cli'
Requires-Dist: textual; extra == 'cli'
Provides-Extra: docs
Requires-Dist: npdoc-to-md>=2.0.1; extra == 'docs'
Requires-Dist: pydoc-markdown>=4.0; extra == 'docs'
Provides-Extra: durable
Requires-Dist: dbos; extra == 'durable'
Requires-Dist: pydantic-ai-slim[dbos]<3,>=2.21.0; extra == 'durable'
Provides-Extra: examples
Requires-Dist: fastapi>=0.116.1; extra == 'examples'
Requires-Dist: pydantic>=2.11.7; extra == 'examples'
Requires-Dist: scikit-learn>=1.7.1; extra == 'examples'
Requires-Dist: streamlit>=1.47.1; extra == 'examples'
Requires-Dist: torch; extra == 'examples'
Requires-Dist: uvicorn; extra == 'examples'
Provides-Extra: google
Requires-Dist: google-api-core>=2.30.3; extra == 'google'
Requires-Dist: google-auth>=2.52.0; extra == 'google'
Requires-Dist: pydantic-ai-slim[google]<3,>=2.21.0; extra == 'google'
Provides-Extra: logfire
Requires-Dist: logfire-api>=4.33.0; extra == 'logfire'
Requires-Dist: logfire>=4.32.1; extra == 'logfire'
Provides-Extra: memory
Requires-Dist: mem0ai>=2.0.1; extra == 'memory'
Provides-Extra: openai
Requires-Dist: openai<3.0.0,>=2.29.0; extra == 'openai'
Requires-Dist: pydantic-ai-slim[openai]<3,>=2.21.0; extra == 'openai'
Provides-Extra: test
Requires-Dist: coverage>=7.9.2; extra == 'test'
Requires-Dist: mypy>=1.16.1; extra == 'test'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
Requires-Dist: pytest-cov>=6.2.1; extra == 'test'
Requires-Dist: pytest-jupyter>=0.10.1; extra == 'test'
Requires-Dist: pytest-tornasync; extra == 'test'
Requires-Dist: pytest>=8.4.1; extra == 'test'
Requires-Dist: python-dotenv>=1.1.1; extra == 'test'
Requires-Dist: types-requests>=2.32.4; extra == 'test'
Requires-Dist: typing-extensions>=4.15.0; extra == 'test'
Provides-Extra: ui
Requires-Dist: a2ui-agent-sdk>=0.4.0; extra == 'ui'
Requires-Dist: ag-ui-protocol>=0.1.19; extra == 'ui'
Requires-Dist: agent-client-protocol>=0.7.1; extra == 'ui'
Requires-Dist: mcp-ui-server<1.1.0,>=1.0.0; extra == 'ui'
Description-Content-Type: text/markdown

<!--
  ~ Copyright (c) 2025-2026 Datalayer, Inc.
  ~
  ~ BSD 3-Clause License
-->

[![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)

[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)

# 🤖 🚀 Agent Runtimes

[![Github Actions Status](https://github.com/datalayer/agent-runtimes/actions/workflows/build.yml/badge.svg)](https://github.com/datalayer/agent-runtimes/actions/workflows/build.yml)
[![Netlify Status](https://api.netlify.com/api/v1/badges/f7f9e08a-884f-4f76-b20d-666d5873716c/deploy-status)](https://app.netlify.com/projects/agent-runtimes/deploys)
[![PyPI - Version](https://img.shields.io/pypi/v/agent-runtimes)](https://pypi.org/project/agent-runtimes)

**Agent Runtimes** is a unified library for deploying, managing, and interacting with AI agents across multiple protocols and frameworks. It provides both a Python server for hosting agents and React components for seamless integration into web and desktop applications.

## What is Agent Runtimes?

Agent Runtimes solves the complexity of deploying AI agents by providing:

1. **Protocol Abstraction**: One agent, multiple protocols - deploy your agent once and access it through ACP, Vercel AI SDK, AG-UI, MCP-UI, or A2A without changing your code.

2. **Framework Flexibility**: Write agents using your preferred framework (Pydantic AI, LangChain, Jupyter AI) while maintaining a consistent API.

3. **Cloud Runtime Management**: Built-in integration with Datalayer Cloud Runtimes for launching and managing compute resources with Zustand-based state management.

4. **UI Components**: Pre-built React components (ChatBase, ChatSidebar, ChatFloating) that connect to agents and execute tools directly in the browser.

5. **Tool Ecosystem**: Seamless integration with MCP (Model Context Protocol) tools, custom tools, and built-in utilities for Jupyter notebooks and Lexical documents.

![Agent Runtimes Chat Web](https://images.datalayer.io/product/agent-runtimes/agent-runtimes-example-1.gif)

![Agent Runtimes Chat CLI](https://images.datalayer.io/products/codeai/codeai_short_cut.gif)

## 🌟 Features

### Agent Node
- **Central registration**: Agent nodes register and heartbeat to Datalayer Runtimes APIs.
- **Node configuration**: Runtime mode (`private`, `shared`, `sleep`) and sharing metadata are tracked per node.
- **Tunnel routing**: Agent nodes maintain a tunnel with Datalayer Runtimes to route chat messages between central UI and nodes.
- **Dedicated UI**: Agent Node list/detail UX is available for node observability and operations.
- **End-to-end sync**: Local node state can be synchronized to central services for fleet visibility.

### Multi-Protocol Support
- **ACP (Agent Client Protocol)**: WebSocket-based standard protocol
- **Vercel AI SDK**: Compatible with Vercel's AI SDK for React/Next.js
- **AG-UI**: Lightweight web interface (Pydantic AI native)
- **MCP-UI**: Interactive UI resources protocol with React/Web Components
- **A2A**: Agent-to-agent communication

### Multi-Agent Support
- **Pydantic AI**: Type-safe agents (fully implemented)
- **LangChain**: Complex workflows (adapter ready)
- **Jupyter AI**: Notebook integration (adapter ready)

### Built-in Features
- 🔌 **Flexible Architecture**: Easy to add new agents and protocols
- 🛠️ **Tool Support**: MCP, custom tools, built-in utilities
- 📊 **Observability**: OpenTelemetry integration
- 💾 **Persistence**: DBOS support for durable execution
- 🔒 **Context Optimization**: LLM context management

## Runtime, Snapshot, and Evals Workflows

The runtime-oriented examples and CLI workflows migrated from `datalayer-core` now live here.

### Python Runtime Quickstart

```python
from agent_runtimes.client import RuntimeClient

client = RuntimeClient()

# Execute code in a managed runtime
with client.create_runtime() as runtime:
    response = runtime.execute("print('Hello from Datalayer!')")
    print(response.stdout)
```

### Runtime and Snapshot CLI

```bash
# List available runtimes
datalayer runtime list

# Create a new runtime
datalayer runtime create ai-env --given-name my-runtime-123

# Execute a script in a runtime
datalayer runtime exec my-script.py --agent <agent-id>

# Create a snapshot from a runtime but do not terminate the runtime
datalayer snapshots create <pod-name> my-snapshot 'AI work!' False
```

### Subscription and Credits CLI

```bash
# End-user billing view
datalayer subscriptions show
datalayer subscriptions available
datalayer subscriptions move
datalayer subscriptions topups
datalayer subscriptions dry-run

# Organization and team credits visibility
datalayer usage org-overview --organization-uid <org_uid>
datalayer usage team-overview --team-uid <team_uid>

# Monitoring-driven credit management
datalayer usage org-monitor --organization-uid <org_uid> --window-hours 24
datalayer usage team-monitor --team-uid <team_uid> --window-hours 24

# Credits transfer operations (owners/admins)
datalayer usage org-allocate-team --organization-uid <org_uid> --team-uid <team_uid> --amount 50
datalayer usage org-revoke-team --organization-uid <org_uid> --team-uid <team_uid> --amount 20
datalayer usage team-allocate-member --team-uid <team_uid> --member-uid <member_uid> --amount 15
datalayer usage team-revoke-member --team-uid <team_uid> --member-uid <member_uid> --amount 5
```

### Evals CLI (Multi-Agentspec)

Use comma-separated agentspec ids to create one experiment per agentspec variant:

```bash
# Creates one experiment per agentspec in the list
agent-runtimes evals experiments create my-exp \
  --evalset-id <evalset_id> \
  --agent-spec-ids example-evals,example-evals-nocodemode,example-custom
```

Generate a comparison report:

```bash
agent-runtimes evals report <evalset_id> --run-limit 50 --export
```

How to interpret grouped comparisons in the report:

- `Within-Agentspec Pairwise Latest-Pass Deltas`: compares experiments using the same agentspec id.
- `Cross-Agentspec Pairwise Latest-Pass Deltas`: compares experiments using different agentspec ids.
- Pairwise sections compute all combinations for the selected experiments, not just two agentspecs.

## Examples

The examples demonstrate how to use the Agent Runtimes functionality in various scenarios and frameworks.

### Install

`make examples` starts both the Python agent server and the Vite dev server,
so you need both stacks installed once:

```bash
# 1. Node dependencies for the React examples + Vite dev server.
npm install

# 2. Python package (editable) for the local agent-runtimes server.
#    Use a virtualenv or conda env of your choice.
pip install -e .
```

Optional extras (declared in `pyproject.toml`):

```bash
pip install -e ".[examples]"   # extra agent framework deps used by examples
pip install -e ".[test]"       # pytest and test utilities
pip install -e ".[cli]"        # CLI dependencies
pip install -e ".[chat]"       # chat-related extras
pip install -e ".[docs]"       # docs build dependencies
```

For deterministic installs in CI (and to avoid resolver backtracking), use the
version constraints file:

```bash
pip install -c constraints/py313.txt -e .
```

### Run

```bash
make examples
```

### Agent Node development (UI + server)

For focused Agent Node development, run:

```bash
make agent-node
```

This target starts both:

- the local Python server on port `8765`
- the Vite page for `html/agent-node.html`

Use this mode to iterate on Agent Node configuration flows and central registration behavior.

Expected central visibility semantics:

- show all nodes owned by the current user,
- show other users' nodes only when mode is `shared`.

### Agent Node against local services (`plane local`)

To run Agent Node with local service URLs preconfigured, use:

```bash
make agent-node-local
```

This target applies the `PLANE_LOCAL_*_URL` mappings and exports both
`DATALAYER_*` and `VITE_*` variables so Agent Node sync/tunnel and UI calls are
wired to local services.

Prerequisites:

1. Start the local Plane stack (`plane local`).
2. Export `DATALAYER_API_KEY` for authenticated registration/tunnel calls.

Override any local service URL if needed:

```bash
PLANE_LOCAL_RUNTIMES_URL=http://localhost:19500 make agent-node-local
```

### Docker build notes

Docker image build and release notes were moved to:

- [docker/README.md](docker/README.md)

By default, `make examples` boots the local Vite dev server with every
Datalayer service URLs set to local defaults for agent execution:

| Variable                      | Default                 | Notes                                           |
| ----------------------------- | ----------------------- | ----------------------------------------------- |
| `VITE_BASE_URL`               | `http://localhost:8765` | Local `agent-runtimes` server (`/api/v1/agents/*`) |
| `VITE_BASE_URL_NO_CODEMODE`   | `http://localhost:8765` | Local no-codemode agent endpoint                |
| `VITE_BASE_URL_CODEMODE`      | `http://localhost:8766` | Local codemode agent endpoint                   |

This is the local-first workflow used during development. It avoids accidental
remote calls for the core agent routes even if your shell exports
`DATALAYER_*_URL` values.

### Running with explicit production URLs

If you want to force production URLs for Datalayer services, use:

```bash
make examples:prod
```

This mode uses the `DATALAYER_*_URL` convention from
`datalayer-core` (specifically `datalayer_core/utils/urls.py`)
and propagates those values to the Vite HTML placeholders.

Override any URL on the command line:

```bash
make examples:prod DATALAYER_DEFAULT_URL=https://prod2.datalayer.run
```

### Running against a local `plane local` stack

If you are developing against a local Plane (`plane local`), use:

```bash
make example-local
```

This points each `DATALAYER_*_URL` (and its `VITE_*` frontend counterpart, so
both http and ws traffic stay local) at the matching localhost port exposed by
`plane local` (see `services/plane/datalayer_plane/sbin/local.sh`):

| Variable                       | Default port                  |
| ------------------------------ | ----------------------------- |
| `PLANE_LOCAL_IAM_URL`          | `http://localhost:9700`       |
| `PLANE_LOCAL_RUNTIMES_URL`     | `http://localhost:9500`       |
| `PLANE_LOCAL_SPACER_URL`       | `http://localhost:9900`       |
| `PLANE_LOCAL_LIBRARY_URL`      | `http://localhost:9800`       |
| `PLANE_LOCAL_MANAGER_URL`      | `http://localhost:2100`       |
| `PLANE_LOCAL_AI_AGENTS_URL`    | `http://localhost:4400`       |
| `PLANE_LOCAL_AI_INFERENCE_URL` | `http://localhost:4450`       |
| `PLANE_LOCAL_JUPYTER_MCP_SERVER_URL` | `http://localhost:4404/mcp`   |
| `PLANE_LOCAL_GROWTH_URL`       | `http://localhost:6660`       |
| `PLANE_LOCAL_SUCCESS_URL`      | `http://localhost:3300`       |
| `PLANE_LOCAL_STATUS_URL`       | `http://localhost:4785`       |
| `PLANE_LOCAL_SUPPORT_URL`      | `http://localhost:2200`       |

Override any port on the command line, e.g.:

```bash
PLANE_LOCAL_IAM_URL=http://localhost:9701 make example-local
```

On the main page, you’ll find an example gallery (cards) that break things down into practical building blocks:

- UX patterns (aka GenUI) with protocols like A2UI and AG-UI
- Interactive or triggered workflows
- Agent Identity and Controls with guardrails, monitoring, tool approvals
- Programmatic tooling with Sandbox and Codemode for MCP and Skills
- Outputs and Notifications
- Real-time collaboration with users, subagents, and multi-agent teams
- Custom agents built from Agentspecs
- ...

Each of these concerns deserves more than a one-off solution—they need deep, composable, and pluggable implementations.

## Documentation

The detailed guides for architecture, use cases, interactive chat, key concepts, and runtime configuration are now in Docusaurus docs:

- [Agent Runtimes Overview](https://agent-runtimes.datalayer.tech/)
- [Integrations](https://agent-runtimes.datalayer.tech/integrations)
- [Chat](https://agent-runtimes.datalayer.tech/chat)
- [Protocols](https://agent-runtimes.datalayer.tech/protocols)
- [Programmatic Tools](https://agent-runtimes.datalayer.tech/programmatic-tools)
- [Agent Nodes](https://agent-runtimes.datalayer.tech/nodes)
- [Endpoints](https://agent-runtimes.datalayer.tech/endpoints)
- [CLI](https://agent-runtimes.datalayer.tech/cli)

## Agentspecs

Generated catalogs are produced via:

```bash
make specs
```

Generation scripts are under [scripts/codegen](https://github.com/datalayer/agent-runtimes/tree/main/scripts/codegen), and outputs are written to:

- Python: [agent_runtimes/specs](https://github.com/datalayer/agent-runtimes/tree/main/agent_runtimes/specs)
- TypeScript: [src/specs](https://github.com/datalayer/agent-runtimes/tree/main/src/specs)
