persona-agent: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project

AI persona agents built on Google A2A protocol with FastAPI REST API and MCP tool integration. Personas are defined as YAML/JSON files loaded from examples/personas/.

Commands

# Install dependencies
uv sync

# Lint and format
uv run ruff check .
uv run ruff format .

# CLI commands
uv run persona-agent api              # Start API server
uv run persona-agent list-personas    # List available personas
uv run persona-agent agent-card       # Show A2A agent cards
uv run persona-agent import-persona FILE  # Import persona file

Architecture

Four-layer structure under src/persona_agent/:

• api/ — FastAPI routes, models, dependency injection, API-key auth. REST routes prefixed with /api/v1, A2A routes at /a2a/.
• a2a/ — A2A protocol integration: PersonaAgentExecutor (implements AgentExecutor), AgentCard builder. Each persona is an A2A agent.
• llm/ — LLM client abstraction with OpenAICompatibleClient using the openai SDK directly. Supports any OpenAI-compatible provider.
• mcp/ — DirectMCPManager using the mcp library directly for stdio server lifecycle, tool loading, and execution.

Key Files

• api/server.py — FastAPI app factory and lifespan; wires MCP, persona manager, A2A registry, auth dependency, CORS, and exception handlers.
• api/agent_factory.py — AgentFactory + AgentSession; creates PersonaAgentExecutor instances and tracks sessions with wall-clock timestamps.
• api/persona_manager.py — Persona Pydantic model (id pattern ^[a-z0-9_-]{1,64}$) and PersonaManager filesystem I/O with path-traversal defense.
• api/auth.py — make_api_key_dependency; secrets.compare_digest in a full allow-list loop. Returns 401 on miss, 503 if auth is enabled with no allowed keys.
• api/routes/a2a.py — A2ARegistry; each persona is mounted as an independent ASGI sub-app via A2AFastAPIApplication.build().
• a2a/executor.py — Core agent logic: shared chat() entrypoint, per-context asyncio.Lock, LRU history (200 contexts), MAX_TOOL_ITERATIONS=10.
• llm/client.py — Abstract LLMClient + OpenAICompatibleClient; from_config() reads default_model + model_configs.
• mcp/direct_mcp.py — Direct MCP stdio management with per-server retries (MAX_RETRIES=3) and ${VAR_NAME} env substitution.