Agents and middleware
Look up create_agent and its parameters, init_chat_model, the structured output strategies, and every type, decorator and built-in middleware in coco.agents.middleware.
Look up coco, the agent layer, from the trustcoco distribution.
create_agent
from coco.agents import create_agent
def create_agent(
model: str | BaseChatModel,
tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
*,
system_prompt: str | SystemMessage | None = None,
middleware: Sequence[AgentMiddleware[Any, Any, Any]] = (),
response_format: ResponseFormat[ResponseT] | type[ResponseT] | dict[str, Any] | None = None,
state_schema: type[AgentState[ResponseT]] | None = None,
context_schema: type[ContextT] | None = None,
checkpointer: Checkpointer | None = None,
store: BaseStore | None = None,
interrupt_before: list[str] | None = None,
interrupt_after: list[str] | None = None,
debug: bool = False,
name: str | None = None,
cache: BaseCache[Any] | None = None,
transformers: Sequence[TransformerFactory] | None = None,
) -> CompiledStateGraph[AgentState[ResponseT], ContextT, InputAgentState, OutputAgentState[ResponseT]]Compiles a tool-calling agent graph with middleware. The graph's default recursion_limit is 9,999.
| Parameter | Type | Default | Description |
|---|---|---|---|
model | str | BaseChatModel | Required | A "<provider>:<model>" string, such as "openai:gpt-4o", or a chat model instance. |
tools | Sequence[BaseTool | Callable | dict] | None | None | @tool functions, BaseTool instances, plain callables, or provider tool specs as dicts. |
system_prompt | str | SystemMessage | None | None | The system instruction put before the messages on each model call. |
middleware | Sequence[AgentMiddleware] | () | Middleware instances or decorated hooks, in order. |
response_format | ResponseFormat | type | dict | None | None | A Pydantic model, TypedDict, JSON schema dict, or strategy. See Structured output. |
state_schema | type[AgentState] | None | None | A TypedDict extending AgentState with more fields. |
context_schema | type[ContextT] | None | None | The schema of the read-only context passed with context=.... |
checkpointer | Checkpointer | None | None | Saves thread state, such as InMemorySaver, SqliteSaver, or PostgresSaver. |
store | BaseStore | None | None | A store shared across threads, such as InMemoryStore. |
interrupt_before | list[str] | None | None | Node names to pause before. |
interrupt_after | list[str] | None | None | Node names to pause after. |
debug | bool | False | Logs each step. |
name | str | None | None | The graph's name, used when the agent is a subgraph of another. |
The input is {"messages": [...]}, with dicts such as {"role": "user", "content": "Hello"} or message objects. The output holds messages and, when response_format is set, structured_response.
init_chat_model
from coco.chat_models import init_chat_model
def init_chat_model(
model: str | None = None,
*,
model_provider: str | None = None,
configurable_fields: Literal["any"] | list[str] | tuple[str, ...] | None = None,
config_prefix: str | None = None,
**kwargs: Any,
) -> BaseChatModel | _ConfigurableModelCreates a chat model from a "<provider>:<model>" string or an explicit model_provider. With configurable_fields, each call can set those fields through its config. See Models.
Structured output
From coco.agents.structured_output:
| Class | Description |
|---|---|
AutoStrategy(schema) | Uses ProviderStrategy when the model supports native structured output, and ToolStrategy otherwise. A plain Pydantic class uses this. |
ProviderStrategy(schema, strict=...) | Uses the provider's native structured output API. |
ToolStrategy(schema, tool_message_content=..., handle_errors=...) | Binds the schema as a tool, parses the call's arguments, and can retry on validation errors. |
StructuredOutputValidationError | Raised when the output fails validation and retries run out. |
MultipleStructuredOutputsError | Raised when the model calls more than one structured output tool in a turn. |
Middleware
From coco.agents.middleware. See Middleware for usage.
| Name | Kind | Description |
|---|---|---|
AgentMiddleware | Base class | Implements before_agent, before_model, wrap_model_call, after_model, wrap_tool_call and after_agent, and their a-prefixed async versions. |
ModelRequest | Dataclass | Passed to wrap_model_call: .model, .messages, .system_message, .tools, .tool_choice, .response_format, .state, .runtime, .model_settings. request.override(**kwargs) returns a changed copy. |
ModelResponse | Dataclass | Returned by handler(request) in wrap_model_call: .result, a list of messages, and .structured_response. |
ExtendedModelResponse | Dataclass | A ModelResponse with a Command, for state updates from wrap_model_call. |
ToolCallRequest | Dataclass | Passed to wrap_tool_call: .tool_call (a dict with "name", "args" and "id"), .tool, .state, .runtime. request.override(**kwargs) returns a changed copy. |
@before_agent, @before_model, @after_model, @after_agent | Decorators | Turn a (state, runtime) function, returning a dict, a Command or None, into that hook. |
@wrap_model_call | Decorator | Turns a (request, handler) function into a model-wrapping middleware. |
@wrap_tool_call | Decorator | Turns a (request, handler) function, returning a ToolMessage or Command, into a tool-wrapping middleware. |
@dynamic_prompt | Decorator | Turns a (request) function, returning a string or SystemMessage, into a dynamic system prompt. |
@hook_config | Decorator | Sets can_jump_to=["model", "tools", "end"] on a before_* or after_* hook. |
TracePolicy, omit_payload, configure_trace_policy | Tracing | Scrub payloads from middleware spans. See Trace payload privacy. |
Built-in middleware
| Middleware | Description |
|---|---|
HumanInTheLoopMiddleware | Pauses before the tools in interrupt_on, each set to True, False or an InterruptOnConfig, for a person to approve, edit, or reject. |
ModelCallLimitMiddleware | Limits model calls per run and per thread. |
ToolCallLimitMiddleware | Limits tool calls per run and per thread, for all tools or one. |
ModelRetryMiddleware | Retries failed model calls with exponential backoff and exception filters. |
ModelFallbackMiddleware | Falls back to other models when the primary fails. |
ToolRetryMiddleware | Retries failed tool calls with backoff. |
ToolErrorMiddleware | Turns the tool exceptions its on_error function chooses into error ToolMessage results. Other exceptions propagate. Requires on_error or aon_error. |
PIIMiddleware | Detects and blocks, redacts, masks, or hashes personal information (PIIMatch, PIIDetectionError). |
SummarizationMiddleware | Summarizes older history past a token or message threshold. |
ContextEditingMiddleware | Clears stale tool uses with ClearToolUsesEdit. |
LLMToolSelectorMiddleware | Uses a fast model to pick the relevant tools from a large catalog each turn. |
ProviderToolSearchMiddleware | Configures the provider's own tool search for large toolsets. |
LLMToolEmulator | Emulates tools with a model, for dry runs. |
TodoListMiddleware | Gives the agent tools to keep a task list in its state. |
ShellToolMiddleware | Runs shell commands under an execution policy (HostExecutionPolicy, DockerExecutionPolicy, CodexSandboxExecutionPolicy), with RedactionRule. |
FilesystemFileSearchMiddleware | Gives the agent scoped glob and content search over files. |
Architecture
The framework's design goals, its four layers, the agent loop, state channels and supersteps, checkpointing, local tracing, where Coco's check attaches, and the decisions behind it.
Graphs and checkpointers
Look up StateGraph and CompiledStateGraph methods, the control flow types interrupt, Command, Send and the policies, the prebuilt nodes, and the checkpointers.