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.
Files changed (49) hide show
  1. agent0_runtime-0.1.0/.gitignore +8 -0
  2. agent0_runtime-0.1.0/CHANGELOG.md +10 -0
  3. agent0_runtime-0.1.0/LICENSE +21 -0
  4. agent0_runtime-0.1.0/PKG-INFO +102 -0
  5. agent0_runtime-0.1.0/README.md +74 -0
  6. agent0_runtime-0.1.0/docs/runtime.md +277 -0
  7. agent0_runtime-0.1.0/examples/minimal_agent.py +21 -0
  8. agent0_runtime-0.1.0/pyproject.toml +96 -0
  9. agent0_runtime-0.1.0/src/agent0_runtime/__init__.py +172 -0
  10. agent0_runtime-0.1.0/src/agent0_runtime/backend.py +78 -0
  11. agent0_runtime-0.1.0/src/agent0_runtime/builtin_tools.py +200 -0
  12. agent0_runtime-0.1.0/src/agent0_runtime/capabilities.py +50 -0
  13. agent0_runtime-0.1.0/src/agent0_runtime/client.py +69 -0
  14. agent0_runtime-0.1.0/src/agent0_runtime/credentials.py +85 -0
  15. agent0_runtime-0.1.0/src/agent0_runtime/events.py +151 -0
  16. agent0_runtime-0.1.0/src/agent0_runtime/filesystem.py +243 -0
  17. agent0_runtime-0.1.0/src/agent0_runtime/history.py +155 -0
  18. agent0_runtime-0.1.0/src/agent0_runtime/images.py +167 -0
  19. agent0_runtime-0.1.0/src/agent0_runtime/lifecycle.py +194 -0
  20. agent0_runtime-0.1.0/src/agent0_runtime/loop.py +588 -0
  21. agent0_runtime-0.1.0/src/agent0_runtime/managed.py +78 -0
  22. agent0_runtime-0.1.0/src/agent0_runtime/openai_backend.py +433 -0
  23. agent0_runtime-0.1.0/src/agent0_runtime/plugins.py +141 -0
  24. agent0_runtime-0.1.0/src/agent0_runtime/providers.py +95 -0
  25. agent0_runtime-0.1.0/src/agent0_runtime/py.typed +0 -0
  26. agent0_runtime-0.1.0/src/agent0_runtime/responses.py +267 -0
  27. agent0_runtime-0.1.0/src/agent0_runtime/routing.py +335 -0
  28. agent0_runtime-0.1.0/src/agent0_runtime/routing_backend.py +161 -0
  29. agent0_runtime-0.1.0/src/agent0_runtime/search.py +22 -0
  30. agent0_runtime-0.1.0/src/agent0_runtime/session.py +75 -0
  31. agent0_runtime-0.1.0/src/agent0_runtime/shell.py +190 -0
  32. agent0_runtime-0.1.0/src/agent0_runtime/skills/websearch/SKILL.md +82 -0
  33. agent0_runtime-0.1.0/src/agent0_runtime/tools.py +335 -0
  34. agent0_runtime-0.1.0/src/agent0_runtime/types.py +153 -0
  35. agent0_runtime-0.1.0/src/agent0_runtime/web_fetch.py +285 -0
  36. agent0_runtime-0.1.0/src/agent0_runtime/web_search.py +295 -0
  37. agent0_runtime-0.1.0/tests/responses_fakes.py +165 -0
  38. agent0_runtime-0.1.0/tests/test_assistant.py +109 -0
  39. agent0_runtime-0.1.0/tests/test_builtin_tools.py +313 -0
  40. agent0_runtime-0.1.0/tests/test_filesystem.py +28 -0
  41. agent0_runtime-0.1.0/tests/test_images.py +57 -0
  42. agent0_runtime-0.1.0/tests/test_managed.py +64 -0
  43. agent0_runtime-0.1.0/tests/test_routing.py +43 -0
  44. agent0_runtime-0.1.0/tests/test_runtime.py +438 -0
  45. agent0_runtime-0.1.0/tests/test_shell.py +114 -0
  46. agent0_runtime-0.1.0/tests/test_simple_api.py +292 -0
  47. agent0_runtime-0.1.0/tests/test_web_fetch.py +239 -0
  48. agent0_runtime-0.1.0/tests/test_web_search.py +61 -0
  49. agent0_runtime-0.1.0/tests/test_web_search_api.py +304 -0
@@ -0,0 +1,8 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .venv/
5
+ build/
6
+ dist/
7
+ .pytest_cache/
8
+ .ruff_cache/
@@ -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
+ ]