Agents Module API Specification

Version: v1.1.9 | Status: Stable | Last Updated: March 2026

1. Overview

The agents module is the core framework for AI agent integration in Codomyrmex. It provides abstract interfaces, concrete client implementations for 12 providers, response parsing utilities, multi-agent pooling, evaluation, and conversation history.

2. Core Components

2.1 Base Classes

• AgentInterface: The protocol that all agents must implement
• BaseAgent: Common functionality (execute, validate, test_connection)
• APIAgentBase: Base for HTTP API-based agents (error handling, token extraction, client init)
• CLIAgentBase: Base for CLI wrapper agents (subprocess execution, streaming, health checks)

2.2 Provider Clients

API-based (extend APIAgentBase)

Client	Module	Provider	Default Model	Env Var
ClaudeClient	claude/	Anthropic	claude-3-opus-20240229	ANTHROPIC_API_KEY
CodexClient	codex/	OpenAI	code-davinci-002	OPENAI_API_KEY
O1Client	o1/	OpenAI	o1	OPENAI_API_KEY
DeepSeekClient	deepseek/	DeepSeek	deepseek-coder	DEEPSEEK_API_KEY
QwenClient	qwen/	Alibaba	qwen-coder-plus	DASHSCOPE_API_KEY

CLI-based (extend CLIAgentBase)

Client	Module	Binary	Features
JulesClient	jules/	jules	Command-based execution
OpenCodeClient	opencode/	opencode	Open-source CLI
GeminiClient	gemini/	gemini	OAuth/API key, slash commands, @ files
MistralVibeClient	mistral_vibe/	vibe	Mistral AI models
EveryCodeClient	every_code/	code	Multi-agent orchestration, browser
OpenClawClient	openclaw/	openclaw	OpenClaw CLI agent

Local

Provider	Module	Access	Features
Ollama	llm/ollama/	HTTP to localhost:11434	Local model management, execution

2.3 Infrastructure

• AgentPool (pooling/): Load balancing, circuit breakers, failover
• AgentBenchmark (evaluation/): Scoring, test cases, composite metrics
• ConversationManager (history/): In-memory, file, SQLite stores
• AgentRegistry (agent_setup/): Declarative catalog, live probes, YAML persistence
• CapabilityCatalog (navigation/): Stable read-only index of agents, modules, and MCP tools

2.4 Utilities

• CodeEditor: AI-driven code modifications
• parse_json_response: Extracts JSON from LLM output
• parse_code_blocks: Extracts markdown code blocks
• parse_structured_output: Key-value field extraction
• clean_response: Sanitizes raw LLM text

2.5 Data Structures

• AgentRequest: Encapsulates input prompt, context, and parameters
• AgentResponse: Encapsulates output text, error, metadata, tokens, execution time
• AgentConfig: Configuration dataclass with env var fallbacks for all 12 agents
• AgentCapabilities: Enum (CODE_GENERATION, CODE_EDITING, CODE_ANALYSIS, TEXT_COMPLETION, STREAMING, MULTI_TURN)

3. Interface Contract

class AgentInterface(ABC):
    def execute(self, request: AgentRequest) -> AgentResponse: ...
    def stream(self, request: AgentRequest) -> Iterator[str]: ...
    def setup(self) -> None: ...
    def test_connection(self) -> bool: ...

4. Usage Examples

Basic execution

from codomyrmex.agents import ClaudeClient, AgentRequest

client = ClaudeClient()
request = AgentRequest(prompt="Write a fibonacci function in Python")
response = client.execute(request)
print(response.content)

Agent discovery

from codomyrmex.agents.agent_setup import AgentRegistry

registry = AgentRegistry()
for result in registry.probe_all():
    print(f"{result.name}: {result.status}")

# Navigation never performs live health probes or executes handlers.
from codomyrmex.agents.navigation import build_capability_catalog

catalog = build_capability_catalog(include_tools=True)
for capability in catalog.search("dispatch", kind="agent"):
    print(capability.id, capability.status)

Setup wizard

uv run python -m codomyrmex.agents.agent_setup

5. Exception Hierarchy

AgentError (base)
├── AgentTimeoutError
├── AgentConfigurationError
├── ExecutionError
├── ToolError
├── ContextError
├── SessionError
├── JulesError
├── ClaudeError
├── CodexError
├── OpenCodeError
├── GeminiError
├── MistralVibeError
└── EveryCodeError

6. Navigation

• README: README.md
• Specification: SPEC.md
• Comparison: AGENT_COMPARISON.md