# {{ name }}

{{ description }}

This project was scaffolded with `a2a init`. It starts as a DeepAgents-backed
A2A agent that uses caller-provided LLM credentials from `ctx.llm`.

## Durable Files

A2A Cloud workspaces are grant-scoped and backed by MinIO. Files become durable
when your agent uses one of the platform-owned file paths:

- `ctx.workspace` for direct workspace reads and writes
- `ctx.write_artifact(...)` for explicit output artifacts
- `ctx.sandbox` for commands that read or write under `/workspace`
- `ctx.workspace_backend()` for framework file tools such as DeepAgents

DeepAgents has its own built-in file tools (`write_file`, `read_file`,
`edit_file`). Without an A2A backend, those tools write into LangGraph state
only, so files can appear to the agent but never reach MinIO or `/workspace`.

Keep this line when building DeepAgents graphs:

```python
return create_deep_agent(
    model=model,
    backend=ctx.workspace_backend(),
    tools=[...],
    system_prompt=SYSTEM_PROMPT,
)
```

The backend respects the caller's grant. In handoffs, generated files should go
under the granted output area, usually `outputs/<name>` or
`/workspace/outputs/<name>`. Writes outside the grant are denied instead of
silently becoming private virtual files.

Avoid writing important results to process-local paths such as `/tmp/result.csv`.
Use `/workspace/outputs/...`, `ctx.write_artifact(...)`, or DeepAgents file tools
with `backend=ctx.workspace_backend()` so the caller can download and inspect the
result.

## Run Locally

```bash
python -m pip install -r requirements.txt
a2a dev
a2a test
a2a test --invoke --skill summarize --args-json '{"text":"hello"}'
a2a card
```

`a2a dev` loads `.env.local`, creates `.a2a/workspace/{inputs,outputs}`, serves
the same HTTP invoke/card/MCP endpoints as production, and hot reloads local
code. Files written through `ctx.workspace_backend()` land under
`.a2a/workspace/outputs` before you deploy.

## Auth

The template is public by default (`auth_model = NoAuth`). To require the
caller's app login, declare a typed auth model and resolver in `agent.py`.
Resolvers receive the inbound bearer token and return the principal exposed as
`ctx.auth`.

```python
from a2a_pack import JWTAuth, OIDCUserInfoAuthResolver

auth_model = JWTAuth
auth_resolver = OIDCUserInfoAuthResolver(
    "https://auth.example.com/oauth2/userinfo",
    auth_model=JWTAuth,
)
```

For homegrown auth or SAML-backed apps, expose a bearer-token `/me` or
`/introspect` endpoint and use the same resolver contract.

## Deploy

```bash
a2a deploy
```
