Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,37 @@ spec:

This will create a new Sandbox named `my-sandbox` running the image you specify. You can then access the Sandbox using its stable hostname, `my-sandbox`.

For more complex examples, including how to use the extensions, please see the [examples/](examples/) and [extensions/examples/](extensions/examples/) directories.
For a more programatic approach you can use the [SDK](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/clients/python/agentic-sandbox-client/README.md) like the following:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should use relative links so that it moves with git commits

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo

Suggested change
For a more programatic approach you can use the [SDK](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/clients/python/agentic-sandbox-client/README.md) like the following:
For a more programmatic approach you can use the [SDK](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/clients/python/agentic-sandbox-client/README.md) like the following:

```python
from agentic_sandbox import Sandbox

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link to the SDK points to the README on the main branch. This could become outdated. Consider linking to the directory /clients/python/agentic-sandbox-client/ instead, which is a more stable reference.

# The SDK abstracts all YAML into a simple context manager
try:
with Sandbox(
template_name="python-runtime-template",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to the namespace, the template_name is hardcoded. It would be beneficial to add a small note explaining that this template must be available on the cluster for the example to work.

namespace="ai-agents"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using a hardcoded namespace like ai-agents might cause the example to fail for users who don't have this namespace created or don't have permissions to access it. Consider adding a comment mentioning that this namespace must exist, or suggest a more common default like default.

) as sandbox:

print("--- Sandbox is Ready! ---")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we remove these prints, as this makes the example more verbose than necessary, and the focus should be on showing the syntax.


# 1. Run a command inside the secure sandbox
result = sandbox.run("echo 'Hello from inside the sandbox!'")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example doesn't check if the command executed successfully. The result object from sandbox.run() should be checked for an error or a non-zero exit code to ensure the command didn't fail silently. A robust example should include error handling for the execution result.

print(f"Stdout: {result.stdout.strip()}")

# 2. Write and read files
sandbox.write("test.txt", "This is a test file.")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The write() method appears to take a string, while the read() method returns bytes that need decoding. This asymmetry in the API could be confusing. It would be clearer if the example showed encoding the string before writing, e.g., sandbox.write("test.txt", "This is a test file.".encode('utf-8')), to make the process more explicit.

content = sandbox.read("test.txt").decode('utf-8')
print(f"Read content: {content}")

except Exception as e:
print(f"An error occurred: {e}")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Catching the generic Exception is a bit broad. If the SDK has its own exception types (e.g., for connection errors, sandbox creation failures), it would be better to catch those specifically. If not, a comment explaining that this is simplified for the example would be helpful.


# The 'with' block automatically handles cleanup
print("--- Sandbox Cleaned Up ---")
```


For more complex examples, including how to use the extensions, please see the [examples/](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/examples/) and [extensions/examples/](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/extensions/examples/) directories.

## Motivation

Expand Down