The Technique — Building Persistent Agents with a2a
The Claude Agent SDK is powerful for prototyping, but moving to production requires handling persistence, state, and observability. The open-source a2a (Agent-to-Agent) tool solves this. It's a CLI and framework that wraps Claude Code, adding three critical layers:
- Skill Management: Define reusable functions (skills) your agent can call. Unlike one-off prompts, these are versioned, documented, and callable by name.
- Persistence & Context Management: Agents maintain memory across conversations. The tool manages context windows, automatically pruning or summarizing to stay within limits while preserving key details.
- Observability: Log all agent interactions, skill calls, and token usage. This is essential for debugging and improving production agents.
Why It Works — Structured State Over Ad-Hoc Prompts
Building complex agents with just claude code and prompts hits limits. You manually juggle context, re-explain goals each session, and have no audit trail. a2a imposes a lightweight structure.
It uses a simple YAML file (agent.yaml) to define your agent's skills, initial context, and persistence rules. The CLI then runs the agent, handling the orchestration. This separates the agent's logic (in skills) from its state (managed by the tool). The result is an agent you can stop, start, and query days later, and it remembers its mission.
How To Apply It — From Prototype to Production in 3 Steps
1. Install and Initialize
# Install the CLI
pip install a2a-cli
# Create a new agent in your project directory
a2a init my-assistant
This creates an agent.yaml and a skills/ directory.
2. Define Skills
Edit skills/example_skill.py. Skills are just Python functions with a docstring that becomes the LLM's description.
def search_web(query: str) -> str:
"""Searches the web for the given query and returns a summary."""
# Your implementation (e.g., using Serper API)
return f"Results for {query}: ..."
List the skill in agent.yaml:
skills:
- name: search_web
description: Searches the web for current information.
3. Run with Persistence
Run your agent with state saved to a local SQLite file:
a2a run --persist ./agent_state.db
Your agent now runs in a loop, can call search_web, and its conversation context is saved. Stop it with CTRL+C and restart later with the same command—it will load prior context.
Key CLI Commands for Development
a2a run --persist ./state.db: The main command for a persistent agent.a2a skills list: View all available skills.a2a logs: Show the interaction log for observability.a2a context --summary: Get a summary of the agent's current persisted memory.
This workflow turns a conversational prototype into a durable tool. Instead of pasting a massive CLAUDE.md each time, you bootstrap an agent with a known state and capabilities.
