114 lines
3.7 KiB
Markdown
114 lines
3.7 KiB
Markdown
---
|
|
name: workspace-artifact-safety
|
|
description: Write A2A agents that use ctx.workspace_backend, workspace grants, artifacts, sandbox commands, and file paths safely. Use for agents that read files, create outputs, run subprocesses, convert media, or return downloadable artifacts.
|
|
---
|
|
# Workspace And Artifact Safety
|
|
|
|
Generated agents run with explicit workspace grants. File work must fit those
|
|
grants and produce artifacts callers can find.
|
|
|
|
## Workspace Access
|
|
|
|
If `agent.py` uses `ctx.workspace`, `ctx.workspace_backend()`, or a DeepAgents
|
|
graph with file tools, declare workspace access on the class:
|
|
|
|
```python
|
|
from a2a_pack import WorkspaceAccess, WorkspaceMode
|
|
|
|
workspace_access = WorkspaceAccess.dynamic(
|
|
max_files=128,
|
|
allowed_modes=(WorkspaceMode.READ_ONLY, WorkspaceMode.READ_WRITE_OVERLAY),
|
|
require_reason=False,
|
|
)
|
|
```
|
|
|
|
Pass the backend into DeepAgents:
|
|
|
|
```python
|
|
backend = ctx.workspace_backend()
|
|
graph = create_deep_agent(model=model, backend=backend, skills=skill_sources or None)
|
|
```
|
|
|
|
Write durable model-created files under `/workspace/outputs/...` in prompts.
|
|
When writing through `ctx.workspace`, use workspace-relative paths such as
|
|
`outputs/report.md`.
|
|
|
|
## Artifact Pattern
|
|
|
|
For user-visible outputs, return a small JSON object and emit an artifact:
|
|
|
|
```python
|
|
async def save_report(ctx: RunContext[NoAuth], report: str) -> dict[str, str]:
|
|
ref = await ctx.write_artifact(
|
|
"report.md",
|
|
report.encode("utf-8"),
|
|
"text/markdown",
|
|
)
|
|
await ctx.emit_artifact(ref)
|
|
return {"artifact_uri": ref.uri, "name": ref.name}
|
|
```
|
|
|
|
For binary files, use the correct media type:
|
|
|
|
```python
|
|
ref = await ctx.write_artifact("frames.zip", zip_bytes, "application/zip")
|
|
await ctx.emit_artifact(ref)
|
|
```
|
|
|
|
## Bounded Subprocesses
|
|
|
|
Media, rendering, archive, and data conversion agents must not run unbounded
|
|
commands. Use explicit timeouts and return structured errors:
|
|
|
|
```python
|
|
import asyncio
|
|
|
|
|
|
async def run_checked(cmd: list[str], timeout_s: int = 120) -> dict[str, str | int]:
|
|
try:
|
|
proc = await asyncio.create_subprocess_exec(
|
|
*cmd,
|
|
stdout=asyncio.subprocess.PIPE,
|
|
stderr=asyncio.subprocess.PIPE,
|
|
)
|
|
stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout_s)
|
|
except asyncio.TimeoutError:
|
|
return {"ok": 0, "error": "command timed out", "timeout_s": timeout_s}
|
|
return {
|
|
"ok": 1 if proc.returncode == 0 else 0,
|
|
"returncode": proc.returncode,
|
|
"stdout": stdout.decode("utf-8", errors="replace")[-4000:],
|
|
"stderr": stderr.decode("utf-8", errors="replace")[-4000:],
|
|
}
|
|
```
|
|
|
|
If a nonzero command still produced a usable output, preserve the output and
|
|
include the command failure as a warning instead of discarding the file.
|
|
|
|
## Scope Expansion
|
|
|
|
Only use `ctx.request_scope(...)` when the public `@skill` declares
|
|
`allow_scope_expansion=True`. Explain the reason in plain language and keep
|
|
the requested read/write patterns narrow.
|
|
|
|
```python
|
|
@skill(
|
|
description="Analyze a protected folder after the caller approves access",
|
|
allow_scope_expansion=True,
|
|
)
|
|
async def analyze_folder(ctx: RunContext[NoAuth], folder: str) -> dict[str, str]:
|
|
await ctx.request_scope(
|
|
reason=f"Need to read {folder} to analyze the requested files",
|
|
read=(f"{folder.rstrip('/')}/**",),
|
|
mode="read_only",
|
|
)
|
|
return {"status": "approved"}
|
|
```
|
|
|
|
## Safety Checklist
|
|
|
|
Do not hard-code absolute local paths. Do not expose arbitrary shell command
|
|
strings as public inputs. Do not write secrets to artifacts. Do not use
|
|
`wants_cp_jwt=True` for normal agents. Do not assume a file exists; check and
|
|
return a structured error that the caller can act on.
|