>cogtrix v0.5.2

Docs/Reference/Code/Agent core

Agent core

Public Python surface for the agent runtime — the state schema, the system-prompt builder, the named-agent registry, and the tool-safety enforcement layer.

Python API note. Imports resolve as cogtrix_core.agent.*. Releases up to and including 0.5.1 used a bare src.agent.* namespace; 0.5.2 renamed the package to stop it polluting the global import space.

Where the run loop lives. The per-turn entry point is run_agent() in cogtrix_core.orchestration.runner — not in agent.core. agent.core builds the pieces that run_agent() assembles.

cogtrix_core.agent.core

Defines the graph state schema, the system-prompt builder, and the LLM factory used by the orchestration layer.

Key symbols:

  • CogtrixState — the TypedDict graph state (messages: Annotated[Sequence[BaseMessage], add_messages]).
  • build_system_prompt(...) — assemble the system prompt from mode additions and tool instructions.
  • build_agent_executor(...) — legacy ReAct executor builder, used by delegate sub-agents.
  • prepare_messages_with_context(...) — token-aware trimming of history before an LLM call.
  • create_llm_from_provider_config(config) — construct a chat model from a resolved provider config.
  • AgentRunner — the Protocol an orchestration runner satisfies.

cogtrix_core.agent.registry

The named-agent registry — the AGENTS.md / /agents system, not the tool registry. It loads named agent definitions (system prompt + tool policy) and filters the toolbox per agent. (For the tool registry, see cogtrix_core.tools.)

Key symbols:

  • AgentRegistry — holds registered AgentConfig definitions.
  • AgentConfig — one named agent: prompt, allowed tools, metadata.
  • register(config) / get(name) / list_agents() — register and look up agents.
  • load_from_config(...) / merge_from_agents_md(...) — load definitions from config and from an AGENTS.md file.
  • filter_tools_for_agent(...) — restrict the active toolset to an agent’s policy.

cogtrix_core.agent.safety

Tool-confirmation gate. Wraps sensitive tools so they prompt for approval before each invocation. See Tool safety.

Key symbols:

  • create_safe_tool_wrapper(...) — wrap a tool so execution is gated by the confirmation UI and the session’s denial/approval state.
  • finalize_tool_for_activation(...) — apply the wrapper (or not) as a tool is activated, keyed off registry.requires_confirmation(name).
  • run_confirmation_prompt(...) — render the prompt and read the user’s y/n/a/d/f/c choice.
  • ConfirmationUI — the Protocol the CLI (Rich) and API (WebSocket) confirmation front-ends implement.
  • ConfirmationResult — enum of the possible choices.
  • UserCancelledRun, AgentExecutionError — control-flow exceptions raised from the gate.