agent0-runtime 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent0_runtime-0.1.0/.gitignore +8 -0
- agent0_runtime-0.1.0/CHANGELOG.md +10 -0
- agent0_runtime-0.1.0/LICENSE +21 -0
- agent0_runtime-0.1.0/PKG-INFO +102 -0
- agent0_runtime-0.1.0/README.md +74 -0
- agent0_runtime-0.1.0/docs/runtime.md +277 -0
- agent0_runtime-0.1.0/examples/minimal_agent.py +21 -0
- agent0_runtime-0.1.0/pyproject.toml +96 -0
- agent0_runtime-0.1.0/src/agent0_runtime/__init__.py +172 -0
- agent0_runtime-0.1.0/src/agent0_runtime/backend.py +78 -0
- agent0_runtime-0.1.0/src/agent0_runtime/builtin_tools.py +200 -0
- agent0_runtime-0.1.0/src/agent0_runtime/capabilities.py +50 -0
- agent0_runtime-0.1.0/src/agent0_runtime/client.py +69 -0
- agent0_runtime-0.1.0/src/agent0_runtime/credentials.py +85 -0
- agent0_runtime-0.1.0/src/agent0_runtime/events.py +151 -0
- agent0_runtime-0.1.0/src/agent0_runtime/filesystem.py +243 -0
- agent0_runtime-0.1.0/src/agent0_runtime/history.py +155 -0
- agent0_runtime-0.1.0/src/agent0_runtime/images.py +167 -0
- agent0_runtime-0.1.0/src/agent0_runtime/lifecycle.py +194 -0
- agent0_runtime-0.1.0/src/agent0_runtime/loop.py +588 -0
- agent0_runtime-0.1.0/src/agent0_runtime/managed.py +78 -0
- agent0_runtime-0.1.0/src/agent0_runtime/openai_backend.py +433 -0
- agent0_runtime-0.1.0/src/agent0_runtime/plugins.py +141 -0
- agent0_runtime-0.1.0/src/agent0_runtime/providers.py +95 -0
- agent0_runtime-0.1.0/src/agent0_runtime/py.typed +0 -0
- agent0_runtime-0.1.0/src/agent0_runtime/responses.py +267 -0
- agent0_runtime-0.1.0/src/agent0_runtime/routing.py +335 -0
- agent0_runtime-0.1.0/src/agent0_runtime/routing_backend.py +161 -0
- agent0_runtime-0.1.0/src/agent0_runtime/search.py +22 -0
- agent0_runtime-0.1.0/src/agent0_runtime/session.py +75 -0
- agent0_runtime-0.1.0/src/agent0_runtime/shell.py +190 -0
- agent0_runtime-0.1.0/src/agent0_runtime/skills/websearch/SKILL.md +82 -0
- agent0_runtime-0.1.0/src/agent0_runtime/tools.py +335 -0
- agent0_runtime-0.1.0/src/agent0_runtime/types.py +153 -0
- agent0_runtime-0.1.0/src/agent0_runtime/web_fetch.py +285 -0
- agent0_runtime-0.1.0/src/agent0_runtime/web_search.py +295 -0
- agent0_runtime-0.1.0/tests/responses_fakes.py +165 -0
- agent0_runtime-0.1.0/tests/test_assistant.py +109 -0
- agent0_runtime-0.1.0/tests/test_builtin_tools.py +313 -0
- agent0_runtime-0.1.0/tests/test_filesystem.py +28 -0
- agent0_runtime-0.1.0/tests/test_images.py +57 -0
- agent0_runtime-0.1.0/tests/test_managed.py +64 -0
- agent0_runtime-0.1.0/tests/test_routing.py +43 -0
- agent0_runtime-0.1.0/tests/test_runtime.py +438 -0
- agent0_runtime-0.1.0/tests/test_shell.py +114 -0
- agent0_runtime-0.1.0/tests/test_simple_api.py +292 -0
- agent0_runtime-0.1.0/tests/test_web_fetch.py +239 -0
- agent0_runtime-0.1.0/tests/test_web_search.py +61 -0
- agent0_runtime-0.1.0/tests/test_web_search_api.py +304 -0
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
- Initial standalone release of the headless agent runtime.
|
|
6
|
+
- Provides the model/tool loop, OpenAI-compatible Responses backend, typed events,
|
|
7
|
+
lifecycle hooks, sessions, cancellation, plugins, provider clients, and generic
|
|
8
|
+
filesystem/shell/web tools.
|
|
9
|
+
- Applications own their terminal UI, persistence formats, credentials paths, and
|
|
10
|
+
product-specific recovery guidance.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 r1cardohj
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: agent0-runtime
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A small embeddable agent runtime with tools, sessions, events, and plugins
|
|
5
|
+
Project-URL: Homepage, https://github.com/r1cardohj/agent0-runtime
|
|
6
|
+
Project-URL: Repository, https://github.com/r1cardohj/agent0-runtime
|
|
7
|
+
Project-URL: Issues, https://github.com/r1cardohj/agent0-runtime/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/r1cardohj/agent0-runtime/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: r1cardohj <2413302357@qq.com>
|
|
10
|
+
License: MIT
|
|
11
|
+
Keywords: agent,agent-runtime,llm,openai-compatible
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: certifi>=2024
|
|
23
|
+
Requires-Dist: openai>=1.40.0
|
|
24
|
+
Requires-Dist: pillow>=12.3.0
|
|
25
|
+
Requires-Dist: trafilatura<3,>=2.3
|
|
26
|
+
Requires-Dist: urllib3>=2
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# agent0-runtime
|
|
30
|
+
|
|
31
|
+
A small, headless, embeddable agent runtime for Python. It provides the model/tool
|
|
32
|
+
loop, OpenAI-compatible Responses backends, tools, sessions, structured events,
|
|
33
|
+
cancellation, lifecycle hooks, and plugins. Terminal UI, persistence formats, and
|
|
34
|
+
application policy belong to consumers.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
python -m pip install agent0-runtime
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Python 3.10 through 3.13 are supported. The package is typed and ships `py.typed`.
|
|
43
|
+
|
|
44
|
+
## Minimal agent
|
|
45
|
+
|
|
46
|
+
Set `DEEPSEEK_API_KEY` or `KIMI_API_KEY`, then run:
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import asyncio
|
|
50
|
+
from agent0_runtime import Agent, tool
|
|
51
|
+
|
|
52
|
+
@tool("add")
|
|
53
|
+
def add(a: float, b: float) -> str:
|
|
54
|
+
"""Add two numbers."""
|
|
55
|
+
return str(a + b)
|
|
56
|
+
|
|
57
|
+
async def main():
|
|
58
|
+
async with Agent.from_env(tools=["add"]) as agent:
|
|
59
|
+
result = await agent.run("Use add to calculate 20 + 22.")
|
|
60
|
+
print(result.text)
|
|
61
|
+
|
|
62
|
+
asyncio.run(main())
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`Agent.from_env()` creates and owns the provider client, backend, and matching history
|
|
66
|
+
policy. Exiting the async context closes plugins and network resources. Pass an explicit
|
|
67
|
+
`provider/model` when more than one provider is configured.
|
|
68
|
+
|
|
69
|
+
Hosts with an existing OpenAI-compatible client can share the same backend/history
|
|
70
|
+
assembly without transferring ownership:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from agent0_runtime import Agent
|
|
74
|
+
|
|
75
|
+
agent = Agent.from_openai(client, model, provider_id=provider_id, tools=registry)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The runtime also includes provider-neutral built-in tools for filesystem, shell, fetch,
|
|
79
|
+
and search. Optional behavior is injected through `BuiltinToolsConfig`; hosts provide
|
|
80
|
+
workspace policy, credentials, persistence, and UI.
|
|
81
|
+
|
|
82
|
+
## Documentation
|
|
83
|
+
|
|
84
|
+
- [Embedding guide](docs/runtime.md)
|
|
85
|
+
- [Minimal example](examples/minimal_agent.py)
|
|
86
|
+
- [Changelog](CHANGELOG.md)
|
|
87
|
+
|
|
88
|
+
## Development
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
python -m pip install -e .
|
|
92
|
+
python -m unittest discover -s tests -v
|
|
93
|
+
python -m pip install ruff==0.12.12 build twine
|
|
94
|
+
ruff check .
|
|
95
|
+
ruff format --check .
|
|
96
|
+
python -m build
|
|
97
|
+
python -m twine check --strict dist/*
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## License
|
|
101
|
+
|
|
102
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# agent0-runtime
|
|
2
|
+
|
|
3
|
+
A small, headless, embeddable agent runtime for Python. It provides the model/tool
|
|
4
|
+
loop, OpenAI-compatible Responses backends, tools, sessions, structured events,
|
|
5
|
+
cancellation, lifecycle hooks, and plugins. Terminal UI, persistence formats, and
|
|
6
|
+
application policy belong to consumers.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
python -m pip install agent0-runtime
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Python 3.10 through 3.13 are supported. The package is typed and ships `py.typed`.
|
|
15
|
+
|
|
16
|
+
## Minimal agent
|
|
17
|
+
|
|
18
|
+
Set `DEEPSEEK_API_KEY` or `KIMI_API_KEY`, then run:
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
import asyncio
|
|
22
|
+
from agent0_runtime import Agent, tool
|
|
23
|
+
|
|
24
|
+
@tool("add")
|
|
25
|
+
def add(a: float, b: float) -> str:
|
|
26
|
+
"""Add two numbers."""
|
|
27
|
+
return str(a + b)
|
|
28
|
+
|
|
29
|
+
async def main():
|
|
30
|
+
async with Agent.from_env(tools=["add"]) as agent:
|
|
31
|
+
result = await agent.run("Use add to calculate 20 + 22.")
|
|
32
|
+
print(result.text)
|
|
33
|
+
|
|
34
|
+
asyncio.run(main())
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`Agent.from_env()` creates and owns the provider client, backend, and matching history
|
|
38
|
+
policy. Exiting the async context closes plugins and network resources. Pass an explicit
|
|
39
|
+
`provider/model` when more than one provider is configured.
|
|
40
|
+
|
|
41
|
+
Hosts with an existing OpenAI-compatible client can share the same backend/history
|
|
42
|
+
assembly without transferring ownership:
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
from agent0_runtime import Agent
|
|
46
|
+
|
|
47
|
+
agent = Agent.from_openai(client, model, provider_id=provider_id, tools=registry)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The runtime also includes provider-neutral built-in tools for filesystem, shell, fetch,
|
|
51
|
+
and search. Optional behavior is injected through `BuiltinToolsConfig`; hosts provide
|
|
52
|
+
workspace policy, credentials, persistence, and UI.
|
|
53
|
+
|
|
54
|
+
## Documentation
|
|
55
|
+
|
|
56
|
+
- [Embedding guide](docs/runtime.md)
|
|
57
|
+
- [Minimal example](examples/minimal_agent.py)
|
|
58
|
+
- [Changelog](CHANGELOG.md)
|
|
59
|
+
|
|
60
|
+
## Development
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
python -m pip install -e .
|
|
64
|
+
python -m unittest discover -s tests -v
|
|
65
|
+
python -m pip install ruff==0.12.12 build twine
|
|
66
|
+
ruff check .
|
|
67
|
+
ruff format --check .
|
|
68
|
+
python -m build
|
|
69
|
+
python -m twine check --strict dist/*
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## License
|
|
73
|
+
|
|
74
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
# Headless runtime and plugin API
|
|
2
|
+
|
|
3
|
+
`agent0_runtime` is a standalone headless runtime for embedding applications. It
|
|
4
|
+
has no imports from terminal UIs, host providers, or application-owned session
|
|
5
|
+
storage. It contains the generic loop plus optional built-in filesystem/shell/web
|
|
6
|
+
tools that applications can select without importing a particular coding product.
|
|
7
|
+
|
|
8
|
+
## Quick start
|
|
9
|
+
|
|
10
|
+
The recommended construction path is `Agent.from_env()`. It discovers a configured
|
|
11
|
+
DeepSeek or Kimi credential, selects that provider's default model, and installs
|
|
12
|
+
the matching Responses backend and history policy:
|
|
13
|
+
|
|
14
|
+
```python
|
|
15
|
+
import asyncio
|
|
16
|
+
from agent0_runtime import Agent, tool
|
|
17
|
+
|
|
18
|
+
@tool("add")
|
|
19
|
+
def add(a: float, b: float) -> str:
|
|
20
|
+
"""Add two numbers."""
|
|
21
|
+
return str(a + b)
|
|
22
|
+
|
|
23
|
+
async def main():
|
|
24
|
+
async with Agent.from_env(tools=["add"]) as agent:
|
|
25
|
+
result = await agent.run("Use add to calculate 20 + 22.")
|
|
26
|
+
print(result.text)
|
|
27
|
+
|
|
28
|
+
asyncio.run(main())
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Set `DEEPSEEK_API_KEY` or `KIMI_API_KEY` before running. With both configured,
|
|
32
|
+
pass an explicit reference such as `Agent.from_env("kimi/kimi-for-coding")`.
|
|
33
|
+
`AGENT0_MODEL` supplies the same default reference, and `AGENT0_BASE_URL` overrides
|
|
34
|
+
the endpoint. No tools are enabled unless supplied. The executable version of this
|
|
35
|
+
example is `examples/minimal_agent.py`.
|
|
36
|
+
|
|
37
|
+
A run without a session is independent. Reuse a `RuntimeSession` for conversation
|
|
38
|
+
history, as shown below. Entering the async context and exiting it closes plugins,
|
|
39
|
+
the backend, and its network client; no separate client cleanup is required.
|
|
40
|
+
|
|
41
|
+
## Typed runs and structured events
|
|
42
|
+
|
|
43
|
+
Ordinary embedders should prefer `Agent.from_env()`. Applications that already own
|
|
44
|
+
an OpenAI-compatible client and route objects can assemble the same typed loop
|
|
45
|
+
without transferring resource ownership:
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from agent0_runtime import OpenAIResponsesBackend, ResponsesHistoryPolicy, Agent
|
|
49
|
+
|
|
50
|
+
backend = OpenAIResponsesBackend(
|
|
51
|
+
client,
|
|
52
|
+
"deepseek-flash",
|
|
53
|
+
provider_id="deepseek",
|
|
54
|
+
context_limit=128_000,
|
|
55
|
+
)
|
|
56
|
+
agent = Agent(
|
|
57
|
+
backend,
|
|
58
|
+
history=ResponsesHistoryPolicy(),
|
|
59
|
+
tools=registry,
|
|
60
|
+
close_backend=False, # the host keeps ownership of its client
|
|
61
|
+
)
|
|
62
|
+
result = await agent.run("fix the tests", cwd=workspace, messages=messages)
|
|
63
|
+
|
|
64
|
+
if result.stop_reason == "max_turns":
|
|
65
|
+
show_blocked(result.turns)
|
|
66
|
+
else:
|
|
67
|
+
show_answer(result.text)
|
|
68
|
+
await agent.close()
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`RunResult` contains `status`, `text`, `turns`, `run_id`, `finish_reason`,
|
|
72
|
+
`stop_reason`, and the latest token usage. Interruption and backend failures are
|
|
73
|
+
still exceptions, with corresponding terminal events emitted first.
|
|
74
|
+
|
|
75
|
+
Each `RuntimeEvent` has a `kind`, per-run sequence number, `run_id`, timestamp,
|
|
76
|
+
optional model-turn number, and a transport-safe payload. Event kinds cover
|
|
77
|
+
model/text/reasoning deltas, routing, usage, compaction, tool start/preview/end,
|
|
78
|
+
and terminal turn states. `event.to_dict()` is suitable for a future JSON-RPC or
|
|
79
|
+
WebSocket adapter. `on_event` may be synchronous or asynchronous.
|
|
80
|
+
|
|
81
|
+
For custom backends, instantiate `agent0_runtime.Agent` directly. The required
|
|
82
|
+
backend protocol is only `complete(request, events) -> ModelTurn`; `model`,
|
|
83
|
+
`provider_id`, `context_limit`, and `prepare()` are optional metadata/policy.
|
|
84
|
+
An owned backend may implement `close()` or `aclose()` to release resources:
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
class Backend:
|
|
88
|
+
async def complete(self, request, events) -> ModelTurn:
|
|
89
|
+
...
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The runtime owns the model integration layer and normally depends on the
|
|
93
|
+
`openai` package. `agent0_runtime.OpenAIResponsesBackend` implements one
|
|
94
|
+
OpenAI-compatible Responses endpoint, including streaming, function calls,
|
|
95
|
+
usage mapping, retry-safe requests, raw Responses history, and client cleanup.
|
|
96
|
+
The runtime owns provider metadata, configurable clients, credential storage,
|
|
97
|
+
model discovery, and `RoutedResponsesBackend` intent/failover. Hosts such as
|
|
98
|
+
hosts inject their credential store, client identity, and provider selection;
|
|
99
|
+
other applications can use the default provider registry, their own router, or
|
|
100
|
+
a different backend entirely.
|
|
101
|
+
|
|
102
|
+
`Agent(backend)` owns and closes its backend by default. Pass
|
|
103
|
+
`close_backend=False` when a host shares that backend or its network client across
|
|
104
|
+
runs. `Agent.close()` and async-context exit are idempotent.
|
|
105
|
+
|
|
106
|
+
Hosts that already own an OpenAI-compatible client should use the same default
|
|
107
|
+
assembly as `from_env()` without transferring client ownership:
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
agent = Agent.from_openai(
|
|
111
|
+
client,
|
|
112
|
+
model,
|
|
113
|
+
provider_id=provider_id,
|
|
114
|
+
context_limit=context_limit,
|
|
115
|
+
tools=registry,
|
|
116
|
+
)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
This factory installs `OpenAIResponsesBackend` and `ResponsesHistoryPolicy`.
|
|
120
|
+
It defaults to `close_backend=False`; the host remains responsible for closing
|
|
121
|
+
the injected client.
|
|
122
|
+
|
|
123
|
+
## Tool registry
|
|
124
|
+
|
|
125
|
+
`@tool` derives names, JSON schemas, required arguments, and descriptions from a
|
|
126
|
+
Python signature and docstring. It works bare as `@tool`, as `@tool("name")`,
|
|
127
|
+
and configured as `@tool(name="...", description="...")`; synchronous and
|
|
128
|
+
asynchronous functions are supported. Common scalar, list, dictionary, literal,
|
|
129
|
+
and optional annotations are supported. Defaults become optional tool arguments.
|
|
130
|
+
The decorated value remains the original Python function, so tests and normal
|
|
131
|
+
calls can use it unchanged.
|
|
132
|
+
|
|
133
|
+
`Agent.from_env()` may receive decorated tool names such as `tools=["add"]`. The
|
|
134
|
+
constructor reflects the calling scope and resolves uniquely named tools. No
|
|
135
|
+
process-global registry is created; an ambiguous or invisible name raises a
|
|
136
|
+
clear error. Function objects remain the best choice for dynamically generated
|
|
137
|
+
or shadowed tools. Use `Tool.define()` when a tool needs an explicit schema or
|
|
138
|
+
`ToolContext`:
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
from agent0_runtime import Agent, OpenAIResponsesBackend, Tool, create_builtin_registry
|
|
142
|
+
|
|
143
|
+
registry = create_builtin_registry()
|
|
144
|
+
registry.register(
|
|
145
|
+
Tool.define(
|
|
146
|
+
"echo",
|
|
147
|
+
"Return text",
|
|
148
|
+
{"text": {"type": "string"}},
|
|
149
|
+
lambda context, args: args["text"],
|
|
150
|
+
required=["text"],
|
|
151
|
+
)
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
backend = OpenAIResponsesBackend(client, "model")
|
|
155
|
+
agent = Agent(backend, tools=registry, close_backend=False)
|
|
156
|
+
result = await agent.run("try echo", cwd=workspace, messages=[])
|
|
157
|
+
await agent.close()
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Handlers receive a `ToolContext` and a decoded argument dictionary. They may be
|
|
161
|
+
synchronous or asynchronous and return `str` or `ToolResult`. Synchronous
|
|
162
|
+
handlers run in a worker thread so they do not block the event loop.
|
|
163
|
+
|
|
164
|
+
## Generic built-in tools
|
|
165
|
+
|
|
166
|
+
The runtime includes provider-neutral `read`, `write`, `edit`, `bash`, `fetch`,
|
|
167
|
+
and `search` definitions. Optional behavior is injected rather than imported:
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
from agent0_runtime import BuiltinToolsConfig, create_builtin_registry, Shell
|
|
171
|
+
|
|
172
|
+
registry = create_builtin_registry(
|
|
173
|
+
BuiltinToolsConfig(
|
|
174
|
+
shell=Shell("bash", ("/bin/bash", "-lc")),
|
|
175
|
+
search_provider=my_search_provider, # any SearchProvider
|
|
176
|
+
)
|
|
177
|
+
)
|
|
178
|
+
agent = Agent(backend, tools=registry)
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
The runtime ships `PillowImageReader` and `DeepSeekSearchProvider`; hosts may inject
|
|
182
|
+
credential resolvers or alternative implementations. Filesystem/shell tools require
|
|
183
|
+
a workspace only when selected by the model, so an assistant with no workspace can
|
|
184
|
+
still use its own tools. Hosts supply their own credential resolvers without
|
|
185
|
+
implementing the search transport itself.
|
|
186
|
+
|
|
187
|
+
## Sessions and stores
|
|
188
|
+
|
|
189
|
+
The core models only portable runtime state:
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
from agent0_runtime import MemorySessionStore, RuntimeSession
|
|
193
|
+
|
|
194
|
+
session = RuntimeSession(
|
|
195
|
+
id="assistant-1",
|
|
196
|
+
messages=[],
|
|
197
|
+
metadata={"persona": "general assistant"},
|
|
198
|
+
)
|
|
199
|
+
result = await agent.run("hello", session=session)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`RuntimeSession` contains an ID, message history, and application metadata.
|
|
203
|
+
`SessionStore` is the portable persistence contract; `MemorySessionStore` supports
|
|
204
|
+
tests and ephemeral agents. Hosts own durable formats, paths, migration, and
|
|
205
|
+
retention policies behind the portable `SessionStore` contract.
|
|
206
|
+
|
|
207
|
+
For explicit per-run state, use `RunContext` and `Agent.run_in_context()`. The
|
|
208
|
+
legacy `cwd` parameter is the filesystem spelling of the optional run workspace;
|
|
209
|
+
neither is required for a non-filesystem agent.
|
|
210
|
+
|
|
211
|
+
## Cancellation
|
|
212
|
+
|
|
213
|
+
A host can cancel its asyncio task for immediate network-stream cancellation,
|
|
214
|
+
or pass a `CancellationToken` for cooperative cancellation:
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
from agent0_runtime import CancellationToken
|
|
218
|
+
|
|
219
|
+
token = CancellationToken()
|
|
220
|
+
result_task = asyncio.create_task(agent.run(..., cancellation=token))
|
|
221
|
+
token.cancel("window closed")
|
|
222
|
+
await result_task # raises AgentInterrupted
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Tokens are checked between runtime boundaries and tools. A token cannot kill an
|
|
226
|
+
arbitrary synchronous plugin already running in a worker thread. On interruption,
|
|
227
|
+
all unanswered model tool calls receive an `error: interrupted` tool message so
|
|
228
|
+
history remains replayable.
|
|
229
|
+
|
|
230
|
+
## Lifecycle hooks
|
|
231
|
+
|
|
232
|
+
`LifecycleHooks` provides ordered, synchronous, read-only observers for session
|
|
233
|
+
and turn boundaries. `subscribe()` returns an unsubscribe callback. Observer
|
|
234
|
+
failures are isolated and recorded in `hooks.errors`; an optional `on_error`
|
|
235
|
+
callback can forward them to a host logger.
|
|
236
|
+
|
|
237
|
+
Lifecycle events distinguish the real `session_id` from `workspace_id`, and turn
|
|
238
|
+
events include the matching `run_id`. Terminal signal handling remains in the
|
|
239
|
+
REPL; outcome classification lives in `core.lifecycle`.
|
|
240
|
+
|
|
241
|
+
## Plugins
|
|
242
|
+
|
|
243
|
+
A plugin registers tools, backend factories, or observers during setup:
|
|
244
|
+
|
|
245
|
+
```python
|
|
246
|
+
class MyPlugin:
|
|
247
|
+
api_version = 1
|
|
248
|
+
|
|
249
|
+
def register(self, context):
|
|
250
|
+
context.tools.register(make_my_tool())
|
|
251
|
+
context.events.subscribe(log_event, kinds=["tool_finished"])
|
|
252
|
+
|
|
253
|
+
async def close(self): # optional
|
|
254
|
+
...
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
Load trusted objects directly with `Agent(..., plugins=[MyPlugin()])`.
|
|
258
|
+
|
|
259
|
+
Installed distributions can advertise an entry point:
|
|
260
|
+
|
|
261
|
+
```toml
|
|
262
|
+
[project.entry-points."agent0.plugins"]
|
|
263
|
+
my_plugin = "my_package:MyPlugin"
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
Discovery only reads metadata. Code is imported solely for names explicitly
|
|
267
|
+
passed as `plugin_names`:
|
|
268
|
+
|
|
269
|
+
```python
|
|
270
|
+
result = await agent.run(...)
|
|
271
|
+
# Construct Agent(..., plugin_names=["my_plugin"]) to load named entry points.
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
There is deliberately no implicit load-all behavior. Python plugins have the
|
|
275
|
+
current user's full privileges and are not sandboxed. The first API supports
|
|
276
|
+
registration and orderly cleanup, not hot reload, arbitrary mutation of the
|
|
277
|
+
loop, or UI-specific hooks.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
"""Run with DEEPSEEK_API_KEY or KIMI_API_KEY set."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
|
|
5
|
+
from agent0_runtime import Agent, tool
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
@tool("add")
|
|
9
|
+
def add(a: float, b: float) -> str:
|
|
10
|
+
"""Add two numbers."""
|
|
11
|
+
return str(a + b)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
async def main():
|
|
15
|
+
async with Agent.from_env(tools=["add"]) as agent:
|
|
16
|
+
result = await agent.run("Use add to calculate 20 + 22.")
|
|
17
|
+
print(result.text)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
if __name__ == "__main__":
|
|
21
|
+
asyncio.run(main())
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "agent0-runtime"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "A small embeddable agent runtime with tools, sessions, events, and plugins"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
requires-python = ">=3.10"
|
|
8
|
+
authors = [
|
|
9
|
+
{ name = "r1cardohj", email = "2413302357@qq.com" },
|
|
10
|
+
]
|
|
11
|
+
keywords = [
|
|
12
|
+
"agent",
|
|
13
|
+
"agent-runtime",
|
|
14
|
+
"llm",
|
|
15
|
+
"openai-compatible",
|
|
16
|
+
]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Development Status :: 3 - Alpha",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"License :: OSI Approved :: MIT License",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.10",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Typing :: Typed",
|
|
27
|
+
]
|
|
28
|
+
dependencies = [
|
|
29
|
+
"openai>=1.40.0",
|
|
30
|
+
"pillow>=12.3.0",
|
|
31
|
+
"trafilatura>=2.3,<3",
|
|
32
|
+
"urllib3>=2",
|
|
33
|
+
"certifi>=2024",
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Homepage = "https://github.com/r1cardohj/agent0-runtime"
|
|
38
|
+
Repository = "https://github.com/r1cardohj/agent0-runtime"
|
|
39
|
+
Issues = "https://github.com/r1cardohj/agent0-runtime/issues"
|
|
40
|
+
Changelog = "https://github.com/r1cardohj/agent0-runtime/blob/main/CHANGELOG.md"
|
|
41
|
+
|
|
42
|
+
[build-system]
|
|
43
|
+
# Hatchling 1.27 emits Metadata-Version 2.5, which current twine validators reject.
|
|
44
|
+
requires = ["hatchling>=1.24,<1.27"]
|
|
45
|
+
build-backend = "hatchling.build"
|
|
46
|
+
|
|
47
|
+
[tool.hatch.build.targets.wheel]
|
|
48
|
+
packages = ["src/agent0_runtime"]
|
|
49
|
+
|
|
50
|
+
[tool.hatch.build.targets.sdist]
|
|
51
|
+
include = [
|
|
52
|
+
"/src",
|
|
53
|
+
"/tests",
|
|
54
|
+
"/docs",
|
|
55
|
+
"/examples",
|
|
56
|
+
"/README.md",
|
|
57
|
+
"/CHANGELOG.md",
|
|
58
|
+
"/LICENSE",
|
|
59
|
+
"/pyproject.toml",
|
|
60
|
+
]
|
|
61
|
+
|
|
62
|
+
[dependency-groups]
|
|
63
|
+
dev = [
|
|
64
|
+
"build>=1.2",
|
|
65
|
+
"ruff==0.12.12",
|
|
66
|
+
"twine>=5",
|
|
67
|
+
]
|
|
68
|
+
|
|
69
|
+
[tool.ruff]
|
|
70
|
+
line-length = 100
|
|
71
|
+
|
|
72
|
+
[tool.ruff.format]
|
|
73
|
+
quote-style = "double"
|
|
74
|
+
|
|
75
|
+
[tool.ruff.lint]
|
|
76
|
+
select = [
|
|
77
|
+
"E",
|
|
78
|
+
"W",
|
|
79
|
+
"F",
|
|
80
|
+
"B",
|
|
81
|
+
"SIM",
|
|
82
|
+
"ARG",
|
|
83
|
+
"PLE",
|
|
84
|
+
"PLW",
|
|
85
|
+
"PLC",
|
|
86
|
+
"I",
|
|
87
|
+
]
|
|
88
|
+
ignore = [
|
|
89
|
+
"N",
|
|
90
|
+
"PLR2004",
|
|
91
|
+
"PLR0911",
|
|
92
|
+
"PLR0912",
|
|
93
|
+
"PLR0913",
|
|
94
|
+
"PLR0915",
|
|
95
|
+
"PLC0415",
|
|
96
|
+
]
|