agent-framework-plimsoll 0.28.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.
- agent_framework_plimsoll-0.28.0/LICENSE +201 -0
- agent_framework_plimsoll-0.28.0/PKG-INFO +197 -0
- agent_framework_plimsoll-0.28.0/README.md +177 -0
- agent_framework_plimsoll-0.28.0/pyproject.toml +42 -0
- agent_framework_plimsoll-0.28.0/setup.cfg +4 -0
- agent_framework_plimsoll-0.28.0/src/agent_framework_plimsoll/__init__.py +32 -0
- agent_framework_plimsoll-0.28.0/src/agent_framework_plimsoll/py.typed +0 -0
- agent_framework_plimsoll-0.28.0/src/agent_framework_plimsoll.egg-info/PKG-INFO +197 -0
- agent_framework_plimsoll-0.28.0/src/agent_framework_plimsoll.egg-info/SOURCES.txt +10 -0
- agent_framework_plimsoll-0.28.0/src/agent_framework_plimsoll.egg-info/dependency_links.txt +1 -0
- agent_framework_plimsoll-0.28.0/src/agent_framework_plimsoll.egg-info/requires.txt +3 -0
- agent_framework_plimsoll-0.28.0/src/agent_framework_plimsoll.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Carroll Guertin
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-framework-plimsoll
|
|
3
|
+
Version: 0.28.0
|
|
4
|
+
Summary: A Microsoft Agent Framework shell tool and code tool that run agent-written commands and code in plimsoll, a self-hosted sandbox that refuses to run below the isolation you require
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll
|
|
7
|
+
Project-URL: Source, https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll
|
|
8
|
+
Project-URL: Issues, https://github.com/plimsollmark/plimsoll/issues
|
|
9
|
+
Keywords: agent-framework,microsoft agent framework,shell,sandbox,code execution,agents,gvisor
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
12
|
+
Classifier: Typing :: Typed
|
|
13
|
+
Requires-Python: >=3.11
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: agent-framework-core==1.26.0
|
|
17
|
+
Requires-Dist: agent-framework-tools==1.0.0b261112
|
|
18
|
+
Requires-Dist: plimsoll-client==0.28.0
|
|
19
|
+
Dynamic: license-file
|
|
20
|
+
|
|
21
|
+
# agent-framework-plimsoll
|
|
22
|
+
|
|
23
|
+
An agent with a shell runs whatever commands its model writes. Microsoft Agent Framework's own `LocalShellTool` runs them
|
|
24
|
+
on your machine ("arbitrary commands run on the host with the agent's privileges", in its own error message), and
|
|
25
|
+
`DockerShellTool` runs them in a container on the agent's machine. This package runs them in plimsoll instead, a
|
|
26
|
+
sandbox service you run yourself, possibly somewhere else, and it has no fallback: if the sandbox is weaker than you
|
|
27
|
+
asked for, nothing runs.
|
|
28
|
+
|
|
29
|
+
It has two parts:
|
|
30
|
+
|
|
31
|
+
- **`PlimsollShellTool`**, the agent's shell over one plimsoll session: the files a command writes, the shell's
|
|
32
|
+
directory and its exported variables are there for the next command.
|
|
33
|
+
- **`plimsoll_code_tool`**, a tool that runs each call's Python or JavaScript in a fresh sandbox.
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
pip install agent-framework-plimsoll
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
It needs a running `plimsolld`, the plimsoll daemon, reachable from the agent
|
|
42
|
+
([getting started (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/getting-started.md)).
|
|
43
|
+
The shell tool needs a provider with sessions: docker (with a project image), E2B or OpenShell today
|
|
44
|
+
([which providers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#which-providers)).
|
|
45
|
+
Sessions are off until the daemon is started with `SANDBOX_MAX_SESSIONS` set (for example `SANDBOX_MAX_SESSIONS=4`);
|
|
46
|
+
without it entering `PlimsollShellTool` raises plimsoll's `UnsupportedError`, saying the daemon has no sessions.
|
|
47
|
+
Python 3.11 or later, as Agent Framework requires.
|
|
48
|
+
|
|
49
|
+
## Use the shell tool
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
from agent_framework import create_harness_agent
|
|
53
|
+
from agent_framework_plimsoll import Client, PlimsollShellTool
|
|
54
|
+
|
|
55
|
+
async with PlimsollShellTool(Client("https://plimsoll.internal:8746", token=TOKEN),
|
|
56
|
+
minimum_isolation="kernel") as shell:
|
|
57
|
+
agent = create_harness_agent(chat_client, shell_executor=shell)
|
|
58
|
+
session = agent.create_session()
|
|
59
|
+
print(await agent.run("Count the lines in every .py file here.", session=session))
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The tool is Agent Framework's shell executor (`start`, `run`, `close`, `as_function`), so the harness gives it to the
|
|
63
|
+
model as its `run_shell` tool and its environment provider runs a few commands through it to tell the model what shell it
|
|
64
|
+
has. With an agent of your own, `client.get_shell_tool(func=shell.as_function())` is the same tool.
|
|
65
|
+
|
|
66
|
+
What the shell tool needs and does:
|
|
67
|
+
|
|
68
|
+
- **The floor is yours to set.** `minimum_isolation` (`process`, `container`, `kernel` or `vm`) has no default. When the
|
|
69
|
+
session opens, its tier is checked against the floor before any command is sent; below it, the session is closed and
|
|
70
|
+
`InsufficientIsolationError` is raised.
|
|
71
|
+
- **One session for the conversation.** A process left running in the background is stopped when its command ends. A
|
|
72
|
+
session left idle is suspended by the daemon and resumes, files kept, on its next command. Once the session has ended
|
|
73
|
+
(its lifetime ran out, the daemon closed it, or you closed the tool), every later command raises `SessionEndedError`;
|
|
74
|
+
the tool never opens a fresh sandbox in its place, because the agent would take it for the one holding its files.
|
|
75
|
+
- **A refusal raises, and a command that may have run stops the run.** A command plimsoll refused before anything ran,
|
|
76
|
+
and a command on an ended session, raise plimsoll's own exceptions, and the model is shown the framework's error result
|
|
77
|
+
("Error: Function failed.", with the detail only if you set the framework's `include_detailed_errors`), never a refusal
|
|
78
|
+
dressed as command output. A command that may have run without an answer to show for it (the answer was lost, the
|
|
79
|
+
run ended without the command's report, or any error plimsoll cannot vouch ran nothing) ends the agent's run instead: `agent.run` raises Agent Framework's
|
|
80
|
+
`MiddlewareFailure`, whose `__cause__` is plimsoll's error, so the model never gets the chance to run it again. They are plimsoll's exceptions, not Agent Framework's own shell errors, because its
|
|
81
|
+
environment provider reads a probe that raises one of those as a command that is not installed. A command that runs
|
|
82
|
+
and fails, and one past its time budget, are normal results.
|
|
83
|
+
- **No human approval by default.** The tool's `approval_mode` is `never_require`: the sandbox, not a person, is the
|
|
84
|
+
boundary. Microsoft's own `LocalShellTool` and `DockerShellTool` default to `always_require`, which asks a person to
|
|
85
|
+
approve each command, so swapping one of them for this tool drops that step unless you keep it:
|
|
86
|
+
`PlimsollShellTool(client, minimum_isolation="kernel", approval_mode="always_require")`.
|
|
87
|
+
- **Every command has a budget,** 120 seconds unless you set `timeout`; `max_timeout` caps any budget. plimsoll enforces
|
|
88
|
+
it: the daemon stops the command and kills whatever it left running.
|
|
89
|
+
- **The shell is the image's.** On plimsoll's docker images that is BusyBox `sh`, not bash; the tool's description tells
|
|
90
|
+
the model so.
|
|
91
|
+
- **The environment provider describes the agent's machine, not the sandbox.** Agent Framework's
|
|
92
|
+
`ShellEnvironmentProvider` tells the model it is "operating a POSIX shell session on" a description of the operating
|
|
93
|
+
system it reads with Python's `platform.platform()` in the agent's own process, which names the agent's host, not
|
|
94
|
+
plimsoll's Alpine image or the sandbox's kernel. Its `instructions_formatter` option replaces that text.
|
|
95
|
+
|
|
96
|
+
## Use the code tool
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
from agent_framework import Agent
|
|
100
|
+
from agent_framework_plimsoll import Client, CodeExecutor, plimsoll_code_tool
|
|
101
|
+
|
|
102
|
+
tool = plimsoll_code_tool(CodeExecutor(Client("https://plimsoll.internal:8746", token=TOKEN)))
|
|
103
|
+
agent = Agent(client=chat_client, tools=[tool])
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The model gets back JSON saying whether the code ran (yes, no with the reason, or unknown), the output, the exit code,
|
|
107
|
+
whether anything was cut short or timed out, the isolation tier the code ran behind, and the SHA-256 of the run's
|
|
108
|
+
record. The tool never raises: a refusal is information for the model, and Agent Framework ends a request after three
|
|
109
|
+
tool errors in a row. `CodeExecutor` requires the `kernel` tier by default. The tool's default language is Python,
|
|
110
|
+
which on docker needs a project image with `python3` in it (`SANDBOX_DOCKER_PROJECT_IMAGE=plimsoll/sandbox-python:latest`):
|
|
111
|
+
on the default image every Python call comes back refused.
|
|
112
|
+
|
|
113
|
+
**One web API, if you grant one.** `CodeExecutor(client, grant_profile="lights", api_description=...)`, with a profile
|
|
114
|
+
the operator configured on the daemon and the description `plimsoll-specgen` wrote for it, lets the code tool's code call
|
|
115
|
+
that profile's routes, and nothing else, through plimsoll's broker, which adds the API's key outside the sandbox.
|
|
116
|
+
JavaScript works on every provider that gives a project run a grant; Python too on docker and openshell, through
|
|
117
|
+
`import plimsoll_host` (pass `languages=("javascript",)` for a daemon elsewhere: the default, Python, is refused there
|
|
118
|
+
when the tool is built). The tool reads the daemon's answer when it is built, offers only the languages that can call
|
|
119
|
+
the API there, and tells the model the routes; the model never names a profile. The code can do whatever an allowed
|
|
120
|
+
route permits and read whatever it returns
|
|
121
|
+
([capability grants (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/capability-grants.md#from-an-agent-kits-code-tool)).
|
|
122
|
+
The shell tool's session takes no grant.
|
|
123
|
+
|
|
124
|
+
## What reaches your application
|
|
125
|
+
|
|
126
|
+
Each command's answer carries what plimsoll states about the call, and nothing of it comes from what the command printed:
|
|
127
|
+
|
|
128
|
+
- **`await shell.run(command)`** returns a `PlimsollShellResult`, Agent Framework's own `ShellResult` with the tier the
|
|
129
|
+
command ran at (`isolation`), the sentence the provider states beside the tier (`isolation_qualification`, empty when
|
|
130
|
+
it states none), how the run ended (`outcome`), the SHA-256 of the run record the client checked (`record_sha256`)
|
|
131
|
+
and the checked result itself (`result`, whose `record` is the record).
|
|
132
|
+
- **Through an agent**, each command's function result keeps the model's text, and its text item's
|
|
133
|
+
`additional_properties` carry the five fields Microsoft's own shell tool puts there (`stdout`, `stderr`, `exit_code`,
|
|
134
|
+
`truncated`, `timed_out`) and plimsoll's labels: `plimsoll_dispatched` (`yes`, `no`, or `unknown` when an error left
|
|
135
|
+
it open), `plimsoll_refused` (the reason, when nothing ran), `plimsoll_outcome`, `plimsoll_isolation`,
|
|
136
|
+
`plimsoll_isolation_qualification` and `plimsoll_record_sha256`. The code tool's function result carries the same
|
|
137
|
+
labels. Each value is checked against the values plimsoll can state and left out if it does not match.
|
|
138
|
+
- **A refusal**, which the shell tool raises, reaches a function middleware of yours as the exception itself, with its
|
|
139
|
+
reason in `not_dispatched`; `call_labels(exception)` gives the same labels.
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
from agent_framework import function_middleware
|
|
143
|
+
from agent_framework_plimsoll import call_labels
|
|
144
|
+
|
|
145
|
+
@function_middleware
|
|
146
|
+
async def record_plimsoll(context, call_next):
|
|
147
|
+
try:
|
|
148
|
+
await call_next()
|
|
149
|
+
except Exception as e:
|
|
150
|
+
log.info("refused or lost: %s", call_labels(e))
|
|
151
|
+
raise
|
|
152
|
+
log.info("ran: %s", context.result[0].additional_properties)
|
|
153
|
+
|
|
154
|
+
agent = create_harness_agent(chat_client, shell_executor=shell, middleware=[record_plimsoll])
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Retries
|
|
158
|
+
|
|
159
|
+
Agent Framework does not run a failed tool call again by itself: a tool's exception becomes one error result for the
|
|
160
|
+
model, and three in a row end the request. After a refusal the model may ask for the same command again, which is safe,
|
|
161
|
+
since nothing ran; after a command that may have run, the run has already stopped. If you add a retry of your own,
|
|
162
|
+
ask `plimsoll_client.retry_on(exception)` first: it says yes only to a refusal plimsoll marked as having run nothing,
|
|
163
|
+
when another try may pass (the daemon was at capacity, or could not be reached before anything was sent). Every other
|
|
164
|
+
error may have followed the command running, and a second run could repeat what it did.
|
|
165
|
+
|
|
166
|
+
## Tracing
|
|
167
|
+
|
|
168
|
+
When Agent Framework's OpenTelemetry instrumentation is on (it is by default) and your application has an OpenTelemetry
|
|
169
|
+
SDK recording spans, the framework opens a span for each tool call, and both tools add plimsoll's labels to it as
|
|
170
|
+
attributes named `plimsoll.dispatched`, `plimsoll.refused`, `plimsoll.outcome`, `plimsoll.isolation`,
|
|
171
|
+
`plimsoll.isolation_qualification` and `plimsoll.record_sha256`, on results and on refusals alike. They never add the
|
|
172
|
+
command, the code or the output. Whether the framework itself records a tool's arguments and result on that span is the
|
|
173
|
+
framework's own sensitive-data setting, not this package's.
|
|
174
|
+
|
|
175
|
+
## What it is not
|
|
176
|
+
|
|
177
|
+
- **Not a hosted service.** You run `plimsolld` on your own machine or cluster, with a provider you pick
|
|
178
|
+
([isolation tiers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/isolation-tiers.md)).
|
|
179
|
+
- **Not attestation.** A reported tier is the daemon's configuration and provider evidence plus a startup check, not
|
|
180
|
+
hardware proof.
|
|
181
|
+
- **Not supported:** an interactive terminal; a session reattached from another process (the tool holds its session in
|
|
182
|
+
the process that opened it); a CodeAct provider (Agent Framework's other way to run code, as Microsoft's Hyperlight
|
|
183
|
+
and Monty packages do).
|
|
184
|
+
|
|
185
|
+
## Versions
|
|
186
|
+
|
|
187
|
+
This package's version moves with plimsoll's releases, and each version requires the `plimsoll-client` release of the
|
|
188
|
+
same number, which holds the code (`plimsoll_client.agent_framework`). `Client`, `CodeExecutor`, `PlimsollShellTool`,
|
|
189
|
+
`PlimsollShellResult`, `plimsoll_code_tool` and `call_labels` here are plimsoll-client's own names, gathered so an agent
|
|
190
|
+
imports from one place. It is tested with, and installs with, exactly `agent-framework-core` 1.26.0 and exactly
|
|
191
|
+
`agent-framework-tools` 1.0.0b261112, the framework's shell tools, a beta released about weekly: pip installs those
|
|
192
|
+
versions beside it and refuses others, and each new release of either is tested before its pin moves. The tool marks itself as the agent's shell with a constant from a private module of Agent
|
|
193
|
+
Framework (`agent_framework._tools.SHELL_TOOL_KIND_VALUE`), as Microsoft's own `DockerShellTool` does; a framework release
|
|
194
|
+
that moves it breaks the import with a message saying so.
|
|
195
|
+
|
|
196
|
+
Licensed under the Apache License 2.0. Source:
|
|
197
|
+
[plimsoll on GitHub (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll).
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# agent-framework-plimsoll
|
|
2
|
+
|
|
3
|
+
An agent with a shell runs whatever commands its model writes. Microsoft Agent Framework's own `LocalShellTool` runs them
|
|
4
|
+
on your machine ("arbitrary commands run on the host with the agent's privileges", in its own error message), and
|
|
5
|
+
`DockerShellTool` runs them in a container on the agent's machine. This package runs them in plimsoll instead, a
|
|
6
|
+
sandbox service you run yourself, possibly somewhere else, and it has no fallback: if the sandbox is weaker than you
|
|
7
|
+
asked for, nothing runs.
|
|
8
|
+
|
|
9
|
+
It has two parts:
|
|
10
|
+
|
|
11
|
+
- **`PlimsollShellTool`**, the agent's shell over one plimsoll session: the files a command writes, the shell's
|
|
12
|
+
directory and its exported variables are there for the next command.
|
|
13
|
+
- **`plimsoll_code_tool`**, a tool that runs each call's Python or JavaScript in a fresh sandbox.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
pip install agent-framework-plimsoll
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
It needs a running `plimsolld`, the plimsoll daemon, reachable from the agent
|
|
22
|
+
([getting started (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/getting-started.md)).
|
|
23
|
+
The shell tool needs a provider with sessions: docker (with a project image), E2B or OpenShell today
|
|
24
|
+
([which providers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#which-providers)).
|
|
25
|
+
Sessions are off until the daemon is started with `SANDBOX_MAX_SESSIONS` set (for example `SANDBOX_MAX_SESSIONS=4`);
|
|
26
|
+
without it entering `PlimsollShellTool` raises plimsoll's `UnsupportedError`, saying the daemon has no sessions.
|
|
27
|
+
Python 3.11 or later, as Agent Framework requires.
|
|
28
|
+
|
|
29
|
+
## Use the shell tool
|
|
30
|
+
|
|
31
|
+
```python
|
|
32
|
+
from agent_framework import create_harness_agent
|
|
33
|
+
from agent_framework_plimsoll import Client, PlimsollShellTool
|
|
34
|
+
|
|
35
|
+
async with PlimsollShellTool(Client("https://plimsoll.internal:8746", token=TOKEN),
|
|
36
|
+
minimum_isolation="kernel") as shell:
|
|
37
|
+
agent = create_harness_agent(chat_client, shell_executor=shell)
|
|
38
|
+
session = agent.create_session()
|
|
39
|
+
print(await agent.run("Count the lines in every .py file here.", session=session))
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The tool is Agent Framework's shell executor (`start`, `run`, `close`, `as_function`), so the harness gives it to the
|
|
43
|
+
model as its `run_shell` tool and its environment provider runs a few commands through it to tell the model what shell it
|
|
44
|
+
has. With an agent of your own, `client.get_shell_tool(func=shell.as_function())` is the same tool.
|
|
45
|
+
|
|
46
|
+
What the shell tool needs and does:
|
|
47
|
+
|
|
48
|
+
- **The floor is yours to set.** `minimum_isolation` (`process`, `container`, `kernel` or `vm`) has no default. When the
|
|
49
|
+
session opens, its tier is checked against the floor before any command is sent; below it, the session is closed and
|
|
50
|
+
`InsufficientIsolationError` is raised.
|
|
51
|
+
- **One session for the conversation.** A process left running in the background is stopped when its command ends. A
|
|
52
|
+
session left idle is suspended by the daemon and resumes, files kept, on its next command. Once the session has ended
|
|
53
|
+
(its lifetime ran out, the daemon closed it, or you closed the tool), every later command raises `SessionEndedError`;
|
|
54
|
+
the tool never opens a fresh sandbox in its place, because the agent would take it for the one holding its files.
|
|
55
|
+
- **A refusal raises, and a command that may have run stops the run.** A command plimsoll refused before anything ran,
|
|
56
|
+
and a command on an ended session, raise plimsoll's own exceptions, and the model is shown the framework's error result
|
|
57
|
+
("Error: Function failed.", with the detail only if you set the framework's `include_detailed_errors`), never a refusal
|
|
58
|
+
dressed as command output. A command that may have run without an answer to show for it (the answer was lost, the
|
|
59
|
+
run ended without the command's report, or any error plimsoll cannot vouch ran nothing) ends the agent's run instead: `agent.run` raises Agent Framework's
|
|
60
|
+
`MiddlewareFailure`, whose `__cause__` is plimsoll's error, so the model never gets the chance to run it again. They are plimsoll's exceptions, not Agent Framework's own shell errors, because its
|
|
61
|
+
environment provider reads a probe that raises one of those as a command that is not installed. A command that runs
|
|
62
|
+
and fails, and one past its time budget, are normal results.
|
|
63
|
+
- **No human approval by default.** The tool's `approval_mode` is `never_require`: the sandbox, not a person, is the
|
|
64
|
+
boundary. Microsoft's own `LocalShellTool` and `DockerShellTool` default to `always_require`, which asks a person to
|
|
65
|
+
approve each command, so swapping one of them for this tool drops that step unless you keep it:
|
|
66
|
+
`PlimsollShellTool(client, minimum_isolation="kernel", approval_mode="always_require")`.
|
|
67
|
+
- **Every command has a budget,** 120 seconds unless you set `timeout`; `max_timeout` caps any budget. plimsoll enforces
|
|
68
|
+
it: the daemon stops the command and kills whatever it left running.
|
|
69
|
+
- **The shell is the image's.** On plimsoll's docker images that is BusyBox `sh`, not bash; the tool's description tells
|
|
70
|
+
the model so.
|
|
71
|
+
- **The environment provider describes the agent's machine, not the sandbox.** Agent Framework's
|
|
72
|
+
`ShellEnvironmentProvider` tells the model it is "operating a POSIX shell session on" a description of the operating
|
|
73
|
+
system it reads with Python's `platform.platform()` in the agent's own process, which names the agent's host, not
|
|
74
|
+
plimsoll's Alpine image or the sandbox's kernel. Its `instructions_formatter` option replaces that text.
|
|
75
|
+
|
|
76
|
+
## Use the code tool
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
from agent_framework import Agent
|
|
80
|
+
from agent_framework_plimsoll import Client, CodeExecutor, plimsoll_code_tool
|
|
81
|
+
|
|
82
|
+
tool = plimsoll_code_tool(CodeExecutor(Client("https://plimsoll.internal:8746", token=TOKEN)))
|
|
83
|
+
agent = Agent(client=chat_client, tools=[tool])
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The model gets back JSON saying whether the code ran (yes, no with the reason, or unknown), the output, the exit code,
|
|
87
|
+
whether anything was cut short or timed out, the isolation tier the code ran behind, and the SHA-256 of the run's
|
|
88
|
+
record. The tool never raises: a refusal is information for the model, and Agent Framework ends a request after three
|
|
89
|
+
tool errors in a row. `CodeExecutor` requires the `kernel` tier by default. The tool's default language is Python,
|
|
90
|
+
which on docker needs a project image with `python3` in it (`SANDBOX_DOCKER_PROJECT_IMAGE=plimsoll/sandbox-python:latest`):
|
|
91
|
+
on the default image every Python call comes back refused.
|
|
92
|
+
|
|
93
|
+
**One web API, if you grant one.** `CodeExecutor(client, grant_profile="lights", api_description=...)`, with a profile
|
|
94
|
+
the operator configured on the daemon and the description `plimsoll-specgen` wrote for it, lets the code tool's code call
|
|
95
|
+
that profile's routes, and nothing else, through plimsoll's broker, which adds the API's key outside the sandbox.
|
|
96
|
+
JavaScript works on every provider that gives a project run a grant; Python too on docker and openshell, through
|
|
97
|
+
`import plimsoll_host` (pass `languages=("javascript",)` for a daemon elsewhere: the default, Python, is refused there
|
|
98
|
+
when the tool is built). The tool reads the daemon's answer when it is built, offers only the languages that can call
|
|
99
|
+
the API there, and tells the model the routes; the model never names a profile. The code can do whatever an allowed
|
|
100
|
+
route permits and read whatever it returns
|
|
101
|
+
([capability grants (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/capability-grants.md#from-an-agent-kits-code-tool)).
|
|
102
|
+
The shell tool's session takes no grant.
|
|
103
|
+
|
|
104
|
+
## What reaches your application
|
|
105
|
+
|
|
106
|
+
Each command's answer carries what plimsoll states about the call, and nothing of it comes from what the command printed:
|
|
107
|
+
|
|
108
|
+
- **`await shell.run(command)`** returns a `PlimsollShellResult`, Agent Framework's own `ShellResult` with the tier the
|
|
109
|
+
command ran at (`isolation`), the sentence the provider states beside the tier (`isolation_qualification`, empty when
|
|
110
|
+
it states none), how the run ended (`outcome`), the SHA-256 of the run record the client checked (`record_sha256`)
|
|
111
|
+
and the checked result itself (`result`, whose `record` is the record).
|
|
112
|
+
- **Through an agent**, each command's function result keeps the model's text, and its text item's
|
|
113
|
+
`additional_properties` carry the five fields Microsoft's own shell tool puts there (`stdout`, `stderr`, `exit_code`,
|
|
114
|
+
`truncated`, `timed_out`) and plimsoll's labels: `plimsoll_dispatched` (`yes`, `no`, or `unknown` when an error left
|
|
115
|
+
it open), `plimsoll_refused` (the reason, when nothing ran), `plimsoll_outcome`, `plimsoll_isolation`,
|
|
116
|
+
`plimsoll_isolation_qualification` and `plimsoll_record_sha256`. The code tool's function result carries the same
|
|
117
|
+
labels. Each value is checked against the values plimsoll can state and left out if it does not match.
|
|
118
|
+
- **A refusal**, which the shell tool raises, reaches a function middleware of yours as the exception itself, with its
|
|
119
|
+
reason in `not_dispatched`; `call_labels(exception)` gives the same labels.
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
from agent_framework import function_middleware
|
|
123
|
+
from agent_framework_plimsoll import call_labels
|
|
124
|
+
|
|
125
|
+
@function_middleware
|
|
126
|
+
async def record_plimsoll(context, call_next):
|
|
127
|
+
try:
|
|
128
|
+
await call_next()
|
|
129
|
+
except Exception as e:
|
|
130
|
+
log.info("refused or lost: %s", call_labels(e))
|
|
131
|
+
raise
|
|
132
|
+
log.info("ran: %s", context.result[0].additional_properties)
|
|
133
|
+
|
|
134
|
+
agent = create_harness_agent(chat_client, shell_executor=shell, middleware=[record_plimsoll])
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Retries
|
|
138
|
+
|
|
139
|
+
Agent Framework does not run a failed tool call again by itself: a tool's exception becomes one error result for the
|
|
140
|
+
model, and three in a row end the request. After a refusal the model may ask for the same command again, which is safe,
|
|
141
|
+
since nothing ran; after a command that may have run, the run has already stopped. If you add a retry of your own,
|
|
142
|
+
ask `plimsoll_client.retry_on(exception)` first: it says yes only to a refusal plimsoll marked as having run nothing,
|
|
143
|
+
when another try may pass (the daemon was at capacity, or could not be reached before anything was sent). Every other
|
|
144
|
+
error may have followed the command running, and a second run could repeat what it did.
|
|
145
|
+
|
|
146
|
+
## Tracing
|
|
147
|
+
|
|
148
|
+
When Agent Framework's OpenTelemetry instrumentation is on (it is by default) and your application has an OpenTelemetry
|
|
149
|
+
SDK recording spans, the framework opens a span for each tool call, and both tools add plimsoll's labels to it as
|
|
150
|
+
attributes named `plimsoll.dispatched`, `plimsoll.refused`, `plimsoll.outcome`, `plimsoll.isolation`,
|
|
151
|
+
`plimsoll.isolation_qualification` and `plimsoll.record_sha256`, on results and on refusals alike. They never add the
|
|
152
|
+
command, the code or the output. Whether the framework itself records a tool's arguments and result on that span is the
|
|
153
|
+
framework's own sensitive-data setting, not this package's.
|
|
154
|
+
|
|
155
|
+
## What it is not
|
|
156
|
+
|
|
157
|
+
- **Not a hosted service.** You run `plimsolld` on your own machine or cluster, with a provider you pick
|
|
158
|
+
([isolation tiers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/isolation-tiers.md)).
|
|
159
|
+
- **Not attestation.** A reported tier is the daemon's configuration and provider evidence plus a startup check, not
|
|
160
|
+
hardware proof.
|
|
161
|
+
- **Not supported:** an interactive terminal; a session reattached from another process (the tool holds its session in
|
|
162
|
+
the process that opened it); a CodeAct provider (Agent Framework's other way to run code, as Microsoft's Hyperlight
|
|
163
|
+
and Monty packages do).
|
|
164
|
+
|
|
165
|
+
## Versions
|
|
166
|
+
|
|
167
|
+
This package's version moves with plimsoll's releases, and each version requires the `plimsoll-client` release of the
|
|
168
|
+
same number, which holds the code (`plimsoll_client.agent_framework`). `Client`, `CodeExecutor`, `PlimsollShellTool`,
|
|
169
|
+
`PlimsollShellResult`, `plimsoll_code_tool` and `call_labels` here are plimsoll-client's own names, gathered so an agent
|
|
170
|
+
imports from one place. It is tested with, and installs with, exactly `agent-framework-core` 1.26.0 and exactly
|
|
171
|
+
`agent-framework-tools` 1.0.0b261112, the framework's shell tools, a beta released about weekly: pip installs those
|
|
172
|
+
versions beside it and refuses others, and each new release of either is tested before its pin moves. The tool marks itself as the agent's shell with a constant from a private module of Agent
|
|
173
|
+
Framework (`agent_framework._tools.SHELL_TOOL_KIND_VALUE`), as Microsoft's own `DockerShellTool` does; a framework release
|
|
174
|
+
that moves it breaks the import with a message saying so.
|
|
175
|
+
|
|
176
|
+
Licensed under the Apache License 2.0. Source:
|
|
177
|
+
[plimsoll on GitHub (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll).
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
# A Microsoft Agent Framework package: a shell tool over one plimsoll session and plimsoll's
|
|
6
|
+
# code tool. The code is plimsoll_client.agent_framework (PlimsollShellTool and
|
|
7
|
+
# plimsoll_code_tool); this package depends on that exact plimsoll-client release, and its
|
|
8
|
+
# version moves with plimsoll's releases (TestClientVersionsAgree in clients/typescript checks
|
|
9
|
+
# both). agent-framework-core and agent-framework-tools need Python 3.11 or later; the suite in
|
|
10
|
+
# clients/python/frameworks/agent_framework runs against the versions below.
|
|
11
|
+
[project]
|
|
12
|
+
name = "agent-framework-plimsoll"
|
|
13
|
+
version = "0.28.0"
|
|
14
|
+
description = "A Microsoft Agent Framework shell tool and code tool that run agent-written commands and code in plimsoll, a self-hosted sandbox that refuses to run below the isolation you require"
|
|
15
|
+
readme = "README.md"
|
|
16
|
+
license = "Apache-2.0"
|
|
17
|
+
license-files = ["LICENSE"]
|
|
18
|
+
requires-python = ">=3.11"
|
|
19
|
+
dependencies = [
|
|
20
|
+
"agent-framework-core==1.26.0",
|
|
21
|
+
# agent-framework-tools, the framework's shell tools, is a beta released about weekly, so
|
|
22
|
+
# it is pinned exactly on purpose: a new beta is tested before the pin moves.
|
|
23
|
+
"agent-framework-tools==1.0.0b261112",
|
|
24
|
+
"plimsoll-client==0.28.0",
|
|
25
|
+
]
|
|
26
|
+
keywords = ["agent-framework", "microsoft agent framework", "shell", "sandbox", "code execution", "agents", "gvisor"]
|
|
27
|
+
classifiers = [
|
|
28
|
+
"Programming Language :: Python :: 3",
|
|
29
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
30
|
+
"Typing :: Typed",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll"
|
|
35
|
+
Source = "https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll"
|
|
36
|
+
Issues = "https://github.com/plimsollmark/plimsoll/issues"
|
|
37
|
+
|
|
38
|
+
[tool.setuptools.packages.find]
|
|
39
|
+
where = ["src"]
|
|
40
|
+
|
|
41
|
+
[tool.setuptools.package-data]
|
|
42
|
+
agent_framework_plimsoll = ["py.typed"]
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
"""Run a Microsoft Agent Framework agent's shell commands and code in plimsoll.
|
|
2
|
+
|
|
3
|
+
from agent_framework import create_harness_agent
|
|
4
|
+
from agent_framework_plimsoll import Client, PlimsollShellTool
|
|
5
|
+
|
|
6
|
+
async with PlimsollShellTool(Client("https://plimsoll.internal:8746", token=TOKEN),
|
|
7
|
+
minimum_isolation="kernel") as shell:
|
|
8
|
+
agent = create_harness_agent(chat_client, shell_executor=shell)
|
|
9
|
+
|
|
10
|
+
from agent_framework_plimsoll import CodeExecutor, plimsoll_code_tool
|
|
11
|
+
|
|
12
|
+
tools = [plimsoll_code_tool(CodeExecutor(Client("https://plimsoll.internal:8746", token=TOKEN)))]
|
|
13
|
+
|
|
14
|
+
The names are plimsoll-client's own, gathered here so an agent imports from one place:
|
|
15
|
+
PlimsollShellTool is plimsoll_client.agent_framework.PlimsollShellTool (one plimsoll session as
|
|
16
|
+
the agent's shell), plimsoll_code_tool is plimsoll_client.agent_framework.plimsoll_code_tool (a
|
|
17
|
+
fresh sandbox per call), Client is plimsoll_client.Client and CodeExecutor is
|
|
18
|
+
plimsoll_client.execution.CodeExecutor. PlimsollShellResult is what the shell tool's run returns
|
|
19
|
+
(the framework's ShellResult with the tier, the provider's sentence, the outcome and the checked
|
|
20
|
+
run record), and call_labels gives plimsoll's closed-set labels for a result or a raised refusal,
|
|
21
|
+
as each function result carries them in additional_properties. The shell tool's floor, minimum_isolation, has no
|
|
22
|
+
default: it is set in your code and checked before any command is sent. CodeExecutor requires
|
|
23
|
+
the kernel isolation tier by default and refuses, before any code is sent, a daemon that states
|
|
24
|
+
less.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from plimsoll_client import Client
|
|
28
|
+
from plimsoll_client.agent_framework import PlimsollShellResult, PlimsollShellTool, call_labels, plimsoll_code_tool
|
|
29
|
+
from plimsoll_client.execution import CodeExecutor
|
|
30
|
+
|
|
31
|
+
__all__ = ["Client", "CodeExecutor", "PlimsollShellResult", "PlimsollShellTool", "call_labels", "plimsoll_code_tool"]
|
|
32
|
+
__version__ = "0.28.0"
|
|
File without changes
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-framework-plimsoll
|
|
3
|
+
Version: 0.28.0
|
|
4
|
+
Summary: A Microsoft Agent Framework shell tool and code tool that run agent-written commands and code in plimsoll, a self-hosted sandbox that refuses to run below the isolation you require
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll
|
|
7
|
+
Project-URL: Source, https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll
|
|
8
|
+
Project-URL: Issues, https://github.com/plimsollmark/plimsoll/issues
|
|
9
|
+
Keywords: agent-framework,microsoft agent framework,shell,sandbox,code execution,agents,gvisor
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
12
|
+
Classifier: Typing :: Typed
|
|
13
|
+
Requires-Python: >=3.11
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: agent-framework-core==1.26.0
|
|
17
|
+
Requires-Dist: agent-framework-tools==1.0.0b261112
|
|
18
|
+
Requires-Dist: plimsoll-client==0.28.0
|
|
19
|
+
Dynamic: license-file
|
|
20
|
+
|
|
21
|
+
# agent-framework-plimsoll
|
|
22
|
+
|
|
23
|
+
An agent with a shell runs whatever commands its model writes. Microsoft Agent Framework's own `LocalShellTool` runs them
|
|
24
|
+
on your machine ("arbitrary commands run on the host with the agent's privileges", in its own error message), and
|
|
25
|
+
`DockerShellTool` runs them in a container on the agent's machine. This package runs them in plimsoll instead, a
|
|
26
|
+
sandbox service you run yourself, possibly somewhere else, and it has no fallback: if the sandbox is weaker than you
|
|
27
|
+
asked for, nothing runs.
|
|
28
|
+
|
|
29
|
+
It has two parts:
|
|
30
|
+
|
|
31
|
+
- **`PlimsollShellTool`**, the agent's shell over one plimsoll session: the files a command writes, the shell's
|
|
32
|
+
directory and its exported variables are there for the next command.
|
|
33
|
+
- **`plimsoll_code_tool`**, a tool that runs each call's Python or JavaScript in a fresh sandbox.
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
pip install agent-framework-plimsoll
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
It needs a running `plimsolld`, the plimsoll daemon, reachable from the agent
|
|
42
|
+
([getting started (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/getting-started.md)).
|
|
43
|
+
The shell tool needs a provider with sessions: docker (with a project image), E2B or OpenShell today
|
|
44
|
+
([which providers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#which-providers)).
|
|
45
|
+
Sessions are off until the daemon is started with `SANDBOX_MAX_SESSIONS` set (for example `SANDBOX_MAX_SESSIONS=4`);
|
|
46
|
+
without it entering `PlimsollShellTool` raises plimsoll's `UnsupportedError`, saying the daemon has no sessions.
|
|
47
|
+
Python 3.11 or later, as Agent Framework requires.
|
|
48
|
+
|
|
49
|
+
## Use the shell tool
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
from agent_framework import create_harness_agent
|
|
53
|
+
from agent_framework_plimsoll import Client, PlimsollShellTool
|
|
54
|
+
|
|
55
|
+
async with PlimsollShellTool(Client("https://plimsoll.internal:8746", token=TOKEN),
|
|
56
|
+
minimum_isolation="kernel") as shell:
|
|
57
|
+
agent = create_harness_agent(chat_client, shell_executor=shell)
|
|
58
|
+
session = agent.create_session()
|
|
59
|
+
print(await agent.run("Count the lines in every .py file here.", session=session))
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The tool is Agent Framework's shell executor (`start`, `run`, `close`, `as_function`), so the harness gives it to the
|
|
63
|
+
model as its `run_shell` tool and its environment provider runs a few commands through it to tell the model what shell it
|
|
64
|
+
has. With an agent of your own, `client.get_shell_tool(func=shell.as_function())` is the same tool.
|
|
65
|
+
|
|
66
|
+
What the shell tool needs and does:
|
|
67
|
+
|
|
68
|
+
- **The floor is yours to set.** `minimum_isolation` (`process`, `container`, `kernel` or `vm`) has no default. When the
|
|
69
|
+
session opens, its tier is checked against the floor before any command is sent; below it, the session is closed and
|
|
70
|
+
`InsufficientIsolationError` is raised.
|
|
71
|
+
- **One session for the conversation.** A process left running in the background is stopped when its command ends. A
|
|
72
|
+
session left idle is suspended by the daemon and resumes, files kept, on its next command. Once the session has ended
|
|
73
|
+
(its lifetime ran out, the daemon closed it, or you closed the tool), every later command raises `SessionEndedError`;
|
|
74
|
+
the tool never opens a fresh sandbox in its place, because the agent would take it for the one holding its files.
|
|
75
|
+
- **A refusal raises, and a command that may have run stops the run.** A command plimsoll refused before anything ran,
|
|
76
|
+
and a command on an ended session, raise plimsoll's own exceptions, and the model is shown the framework's error result
|
|
77
|
+
("Error: Function failed.", with the detail only if you set the framework's `include_detailed_errors`), never a refusal
|
|
78
|
+
dressed as command output. A command that may have run without an answer to show for it (the answer was lost, the
|
|
79
|
+
run ended without the command's report, or any error plimsoll cannot vouch ran nothing) ends the agent's run instead: `agent.run` raises Agent Framework's
|
|
80
|
+
`MiddlewareFailure`, whose `__cause__` is plimsoll's error, so the model never gets the chance to run it again. They are plimsoll's exceptions, not Agent Framework's own shell errors, because its
|
|
81
|
+
environment provider reads a probe that raises one of those as a command that is not installed. A command that runs
|
|
82
|
+
and fails, and one past its time budget, are normal results.
|
|
83
|
+
- **No human approval by default.** The tool's `approval_mode` is `never_require`: the sandbox, not a person, is the
|
|
84
|
+
boundary. Microsoft's own `LocalShellTool` and `DockerShellTool` default to `always_require`, which asks a person to
|
|
85
|
+
approve each command, so swapping one of them for this tool drops that step unless you keep it:
|
|
86
|
+
`PlimsollShellTool(client, minimum_isolation="kernel", approval_mode="always_require")`.
|
|
87
|
+
- **Every command has a budget,** 120 seconds unless you set `timeout`; `max_timeout` caps any budget. plimsoll enforces
|
|
88
|
+
it: the daemon stops the command and kills whatever it left running.
|
|
89
|
+
- **The shell is the image's.** On plimsoll's docker images that is BusyBox `sh`, not bash; the tool's description tells
|
|
90
|
+
the model so.
|
|
91
|
+
- **The environment provider describes the agent's machine, not the sandbox.** Agent Framework's
|
|
92
|
+
`ShellEnvironmentProvider` tells the model it is "operating a POSIX shell session on" a description of the operating
|
|
93
|
+
system it reads with Python's `platform.platform()` in the agent's own process, which names the agent's host, not
|
|
94
|
+
plimsoll's Alpine image or the sandbox's kernel. Its `instructions_formatter` option replaces that text.
|
|
95
|
+
|
|
96
|
+
## Use the code tool
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
from agent_framework import Agent
|
|
100
|
+
from agent_framework_plimsoll import Client, CodeExecutor, plimsoll_code_tool
|
|
101
|
+
|
|
102
|
+
tool = plimsoll_code_tool(CodeExecutor(Client("https://plimsoll.internal:8746", token=TOKEN)))
|
|
103
|
+
agent = Agent(client=chat_client, tools=[tool])
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The model gets back JSON saying whether the code ran (yes, no with the reason, or unknown), the output, the exit code,
|
|
107
|
+
whether anything was cut short or timed out, the isolation tier the code ran behind, and the SHA-256 of the run's
|
|
108
|
+
record. The tool never raises: a refusal is information for the model, and Agent Framework ends a request after three
|
|
109
|
+
tool errors in a row. `CodeExecutor` requires the `kernel` tier by default. The tool's default language is Python,
|
|
110
|
+
which on docker needs a project image with `python3` in it (`SANDBOX_DOCKER_PROJECT_IMAGE=plimsoll/sandbox-python:latest`):
|
|
111
|
+
on the default image every Python call comes back refused.
|
|
112
|
+
|
|
113
|
+
**One web API, if you grant one.** `CodeExecutor(client, grant_profile="lights", api_description=...)`, with a profile
|
|
114
|
+
the operator configured on the daemon and the description `plimsoll-specgen` wrote for it, lets the code tool's code call
|
|
115
|
+
that profile's routes, and nothing else, through plimsoll's broker, which adds the API's key outside the sandbox.
|
|
116
|
+
JavaScript works on every provider that gives a project run a grant; Python too on docker and openshell, through
|
|
117
|
+
`import plimsoll_host` (pass `languages=("javascript",)` for a daemon elsewhere: the default, Python, is refused there
|
|
118
|
+
when the tool is built). The tool reads the daemon's answer when it is built, offers only the languages that can call
|
|
119
|
+
the API there, and tells the model the routes; the model never names a profile. The code can do whatever an allowed
|
|
120
|
+
route permits and read whatever it returns
|
|
121
|
+
([capability grants (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/capability-grants.md#from-an-agent-kits-code-tool)).
|
|
122
|
+
The shell tool's session takes no grant.
|
|
123
|
+
|
|
124
|
+
## What reaches your application
|
|
125
|
+
|
|
126
|
+
Each command's answer carries what plimsoll states about the call, and nothing of it comes from what the command printed:
|
|
127
|
+
|
|
128
|
+
- **`await shell.run(command)`** returns a `PlimsollShellResult`, Agent Framework's own `ShellResult` with the tier the
|
|
129
|
+
command ran at (`isolation`), the sentence the provider states beside the tier (`isolation_qualification`, empty when
|
|
130
|
+
it states none), how the run ended (`outcome`), the SHA-256 of the run record the client checked (`record_sha256`)
|
|
131
|
+
and the checked result itself (`result`, whose `record` is the record).
|
|
132
|
+
- **Through an agent**, each command's function result keeps the model's text, and its text item's
|
|
133
|
+
`additional_properties` carry the five fields Microsoft's own shell tool puts there (`stdout`, `stderr`, `exit_code`,
|
|
134
|
+
`truncated`, `timed_out`) and plimsoll's labels: `plimsoll_dispatched` (`yes`, `no`, or `unknown` when an error left
|
|
135
|
+
it open), `plimsoll_refused` (the reason, when nothing ran), `plimsoll_outcome`, `plimsoll_isolation`,
|
|
136
|
+
`plimsoll_isolation_qualification` and `plimsoll_record_sha256`. The code tool's function result carries the same
|
|
137
|
+
labels. Each value is checked against the values plimsoll can state and left out if it does not match.
|
|
138
|
+
- **A refusal**, which the shell tool raises, reaches a function middleware of yours as the exception itself, with its
|
|
139
|
+
reason in `not_dispatched`; `call_labels(exception)` gives the same labels.
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
from agent_framework import function_middleware
|
|
143
|
+
from agent_framework_plimsoll import call_labels
|
|
144
|
+
|
|
145
|
+
@function_middleware
|
|
146
|
+
async def record_plimsoll(context, call_next):
|
|
147
|
+
try:
|
|
148
|
+
await call_next()
|
|
149
|
+
except Exception as e:
|
|
150
|
+
log.info("refused or lost: %s", call_labels(e))
|
|
151
|
+
raise
|
|
152
|
+
log.info("ran: %s", context.result[0].additional_properties)
|
|
153
|
+
|
|
154
|
+
agent = create_harness_agent(chat_client, shell_executor=shell, middleware=[record_plimsoll])
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Retries
|
|
158
|
+
|
|
159
|
+
Agent Framework does not run a failed tool call again by itself: a tool's exception becomes one error result for the
|
|
160
|
+
model, and three in a row end the request. After a refusal the model may ask for the same command again, which is safe,
|
|
161
|
+
since nothing ran; after a command that may have run, the run has already stopped. If you add a retry of your own,
|
|
162
|
+
ask `plimsoll_client.retry_on(exception)` first: it says yes only to a refusal plimsoll marked as having run nothing,
|
|
163
|
+
when another try may pass (the daemon was at capacity, or could not be reached before anything was sent). Every other
|
|
164
|
+
error may have followed the command running, and a second run could repeat what it did.
|
|
165
|
+
|
|
166
|
+
## Tracing
|
|
167
|
+
|
|
168
|
+
When Agent Framework's OpenTelemetry instrumentation is on (it is by default) and your application has an OpenTelemetry
|
|
169
|
+
SDK recording spans, the framework opens a span for each tool call, and both tools add plimsoll's labels to it as
|
|
170
|
+
attributes named `plimsoll.dispatched`, `plimsoll.refused`, `plimsoll.outcome`, `plimsoll.isolation`,
|
|
171
|
+
`plimsoll.isolation_qualification` and `plimsoll.record_sha256`, on results and on refusals alike. They never add the
|
|
172
|
+
command, the code or the output. Whether the framework itself records a tool's arguments and result on that span is the
|
|
173
|
+
framework's own sensitive-data setting, not this package's.
|
|
174
|
+
|
|
175
|
+
## What it is not
|
|
176
|
+
|
|
177
|
+
- **Not a hosted service.** You run `plimsolld` on your own machine or cluster, with a provider you pick
|
|
178
|
+
([isolation tiers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/isolation-tiers.md)).
|
|
179
|
+
- **Not attestation.** A reported tier is the daemon's configuration and provider evidence plus a startup check, not
|
|
180
|
+
hardware proof.
|
|
181
|
+
- **Not supported:** an interactive terminal; a session reattached from another process (the tool holds its session in
|
|
182
|
+
the process that opened it); a CodeAct provider (Agent Framework's other way to run code, as Microsoft's Hyperlight
|
|
183
|
+
and Monty packages do).
|
|
184
|
+
|
|
185
|
+
## Versions
|
|
186
|
+
|
|
187
|
+
This package's version moves with plimsoll's releases, and each version requires the `plimsoll-client` release of the
|
|
188
|
+
same number, which holds the code (`plimsoll_client.agent_framework`). `Client`, `CodeExecutor`, `PlimsollShellTool`,
|
|
189
|
+
`PlimsollShellResult`, `plimsoll_code_tool` and `call_labels` here are plimsoll-client's own names, gathered so an agent
|
|
190
|
+
imports from one place. It is tested with, and installs with, exactly `agent-framework-core` 1.26.0 and exactly
|
|
191
|
+
`agent-framework-tools` 1.0.0b261112, the framework's shell tools, a beta released about weekly: pip installs those
|
|
192
|
+
versions beside it and refuses others, and each new release of either is tested before its pin moves. The tool marks itself as the agent's shell with a constant from a private module of Agent
|
|
193
|
+
Framework (`agent_framework._tools.SHELL_TOOL_KIND_VALUE`), as Microsoft's own `DockerShellTool` does; a framework release
|
|
194
|
+
that moves it breaks the import with a message saying so.
|
|
195
|
+
|
|
196
|
+
Licensed under the Apache License 2.0. Source:
|
|
197
|
+
[plimsoll on GitHub (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/tree/main/clients/python/agent-framework-plimsoll).
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
src/agent_framework_plimsoll/__init__.py
|
|
5
|
+
src/agent_framework_plimsoll/py.typed
|
|
6
|
+
src/agent_framework_plimsoll.egg-info/PKG-INFO
|
|
7
|
+
src/agent_framework_plimsoll.egg-info/SOURCES.txt
|
|
8
|
+
src/agent_framework_plimsoll.egg-info/dependency_links.txt
|
|
9
|
+
src/agent_framework_plimsoll.egg-info/requires.txt
|
|
10
|
+
src/agent_framework_plimsoll.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
agent_framework_plimsoll
|