Add Agent
Use this skill when working on agent adapters in the Exgentic repository.
First read
Start with:
docs/adding-agents.mdsrc/exgentic/core/agent.pysrc/exgentic/core/agent_instance.pysrc/exgentic/interfaces/registry.py
Then inspect the most relevant existing adapters:
src/exgentic/agents/litellm_tool_calling/litellm_tool_calling_agent.py+instance.py(split pattern: heavy deps in separate file)src/exgentic/agents/cli/claude/agent.py(light pattern: everything in one file)
Workflow
Decide whether to split files. If the agent depends on heavy third-party libraries (litellm, smolagents, openai SDK, etc.), put the Agent in one file and the AgentInstance in
instance.py. If deps are light, keep both in a single file.Implement the Agent class first. Subclass
Agent. Declaredisplay_nameandslug_nameasClassVar[str]. Add user-facing config fields. Implement_get_instance_class()with a lazy import. Implement_get_instance_kwargs()to translate config and the benchmark contract into instance constructor kwargs.Implement the AgentInstance class. Subclass
AgentInstance. Acceptsession_idplus the kwargs from_get_instance_kwargs(). Callsuper().__init__(session_id). Implementreact()as the core decision loop andclose()for cleanup. Optionally overridestart()andget_cost().Add
requirements.txtfor agent-specific dependencies. List only packages not already in the base exgentic install. Place the file in the agent's package directory;RunnerMixindiscovers it automatically.Add
setup.shif non-pip setup is needed. Place it next to the agent module;RunnerMixindiscovers it automatically.Register the agent in
src/exgentic/interfaces/registry.py. Add aRegistryEntryto theAGENTSdict. Ensureslug_nameanddisplay_namematch the class exactly.Validate the adapter as an agent, not just as code. Check registry loading, dependency isolation, at least one end-to-end benchmark run, cost reporting, and cleanup.
Non-negotiable rules
- The Agent file must be importable without installing agent-specific packages.
_get_instance_class()must use a lazy import to isolate heavy deps._get_instance_kwargs()must faithfully pass the benchmark contract (task, context, actions, session_id) through to the instance.- The instance constructor must call
super().__init__(session_id). react()must returnNonewhen the agent decides it is done.close()must not raise exceptions.slug_nameanddisplay_namein the registry entry must exactly match the class values.- The agent must adapt to the benchmark, never the other way around.
Validation
Before finishing, run at least:
python -m py_compileon changed agent filespre-commit run --files ...git diff --check
Also confirm:
load_agent("slug_name")succeeds from a Python shell- The Agent file imports cleanly without agent-specific packages installed
- At least one benchmark runs end to end with the new agent
close()completes without errorget_cost()returns a valid report