Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (67 loc) · 2.79 KB

AGENTS.md

File metadata and controls

87 lines (67 loc) · 2.79 KB

AGENTS.md -- Guide for AI Coding Assistants

This file tells AI assistants (Claude Code, Cursor, Copilot) how to work with agentic-core.

Architecture

agentic-core uses Explicit Architecture (Hexagonal + DDD + CQRS). The dependency rule: all arrows point inward.

Primary Adapters (WebSocket, gRPC)  -- call into -->
  Application Layer (Commands, Queries, Ports, Middleware)  -- uses -->
    Domain Layer (Entities, Value Objects, Events, Services)
  Application Layer  <-- implemented by --
Secondary Adapters (Redis, PostgreSQL, pgvector, FalkorDB, OTel, Langfuse, MCP)

Never import concrete adapters in domain or application code. Only import port ABCs.

Creating a New Graph

  1. Create a persona YAML in agents/:
name: my-agent
role: "Description of what it does"
graph_template: react          # react | plan-and-execute | reflexion | supervisor
tools:
  - mcp_tool_name_*
model_config:
  provider: anthropic
  model: claude-sonnet-4-6
  1. (Optional) Override with code:
from agentic_core.application.services.persona_registry import agent_persona
from agentic_core.graph_templates.base import BaseAgentGraph

@agent_persona("my-agent")
class MyGraph(BaseAgentGraph):
    def build_graph(self):
        # Custom LangGraph StateGraph
        ...

Graph Template Decision Tree

Does your agent use tools?
  No  -> Direct LLM (no graph)
  Yes -> Needs multi-step planning?
           No  -> react (default, 80% of cases)
           Yes -> Steps independent?
                    Yes -> llm-compiler (parallel)
                    No  -> plan-and-execute

Output quality needs retry loops? -> reflexion (wraps any template)
Multiple personas collaborating?  -> supervisor
Full autonomous dev cycles?       -> orchestrator

Key Conventions

  • Domain layer (domain/): Pure Python. Zero external imports. No async.
  • Application layer (application/): Port ABCs, command/query handlers, middleware.
  • Adapters (adapters/): Concrete implementations. Primary = driving (WS, gRPC). Secondary = driven (Redis, PG...).
  • Tests: Mirror source structure in tests/unit/. Integration tests require RUN_INTEGRATION=1.
  • Config: All via env vars with AGENTIC_ prefix. Nested: AGENTIC_DEFAULT_MODEL__MODEL=claude-opus-4-6.

Running

python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v                    # unit tests
make proto                   # regenerate gRPC stubs
make lint                    # ruff
make typecheck               # mypy

SRE Practices

  • Every persona can define slo_targets in YAML (latency_p99, success_rate)
  • SLOTracker publishes SLOBreached events when thresholds are exceeded
  • ChaosHooks available for resilience testing (opt-in)
  • All observability signals correlated via trace_id