Coco
Look something up

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.

ParameterTypeDefaultDescription
modelstr | BaseChatModelRequiredA "<provider>:<model>" string, such as "openai:gpt-4o", or a chat model instance.
toolsSequence[BaseTool | Callable | dict] | NoneNone@tool functions, BaseTool instances, plain callables, or provider tool specs as dicts.
system_promptstr | SystemMessage | NoneNoneThe system instruction put before the messages on each model call.
middlewareSequence[AgentMiddleware]()Middleware instances or decorated hooks, in order.
response_formatResponseFormat | type | dict | NoneNoneA Pydantic model, TypedDict, JSON schema dict, or strategy. See Structured output.
state_schematype[AgentState] | NoneNoneA TypedDict extending AgentState with more fields.
context_schematype[ContextT] | NoneNoneThe schema of the read-only context passed with context=....
checkpointerCheckpointer | NoneNoneSaves thread state, such as InMemorySaver, SqliteSaver, or PostgresSaver.
storeBaseStore | NoneNoneA store shared across threads, such as InMemoryStore.
interrupt_beforelist[str] | NoneNoneNode names to pause before.
interrupt_afterlist[str] | NoneNoneNode names to pause after.
debugboolFalseLogs each step.
namestr | NoneNoneThe 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 | _ConfigurableModel

Creates 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:

ClassDescription
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.
StructuredOutputValidationErrorRaised when the output fails validation and retries run out.
MultipleStructuredOutputsErrorRaised when the model calls more than one structured output tool in a turn.

Middleware

From coco.agents.middleware. See Middleware for usage.

NameKindDescription
AgentMiddlewareBase classImplements before_agent, before_model, wrap_model_call, after_model, wrap_tool_call and after_agent, and their a-prefixed async versions.
ModelRequestDataclassPassed to wrap_model_call: .model, .messages, .system_message, .tools, .tool_choice, .response_format, .state, .runtime, .model_settings. request.override(**kwargs) returns a changed copy.
ModelResponseDataclassReturned by handler(request) in wrap_model_call: .result, a list of messages, and .structured_response.
ExtendedModelResponseDataclassA ModelResponse with a Command, for state updates from wrap_model_call.
ToolCallRequestDataclassPassed 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_agentDecoratorsTurn a (state, runtime) function, returning a dict, a Command or None, into that hook.
@wrap_model_callDecoratorTurns a (request, handler) function into a model-wrapping middleware.
@wrap_tool_callDecoratorTurns a (request, handler) function, returning a ToolMessage or Command, into a tool-wrapping middleware.
@dynamic_promptDecoratorTurns a (request) function, returning a string or SystemMessage, into a dynamic system prompt.
@hook_configDecoratorSets can_jump_to=["model", "tools", "end"] on a before_* or after_* hook.
TracePolicy, omit_payload, configure_trace_policyTracingScrub payloads from middleware spans. See Trace payload privacy.

Built-in middleware

MiddlewareDescription
HumanInTheLoopMiddlewarePauses before the tools in interrupt_on, each set to True, False or an InterruptOnConfig, for a person to approve, edit, or reject.
ModelCallLimitMiddlewareLimits model calls per run and per thread.
ToolCallLimitMiddlewareLimits tool calls per run and per thread, for all tools or one.
ModelRetryMiddlewareRetries failed model calls with exponential backoff and exception filters.
ModelFallbackMiddlewareFalls back to other models when the primary fails.
ToolRetryMiddlewareRetries failed tool calls with backoff.
ToolErrorMiddlewareTurns the tool exceptions its on_error function chooses into error ToolMessage results. Other exceptions propagate. Requires on_error or aon_error.
PIIMiddlewareDetects and blocks, redacts, masks, or hashes personal information (PIIMatch, PIIDetectionError).
SummarizationMiddlewareSummarizes older history past a token or message threshold.
ContextEditingMiddlewareClears stale tool uses with ClearToolUsesEdit.
LLMToolSelectorMiddlewareUses a fast model to pick the relevant tools from a large catalog each turn.
ProviderToolSearchMiddlewareConfigures the provider's own tool search for large toolsets.
LLMToolEmulatorEmulates tools with a model, for dry runs.
TodoListMiddlewareGives the agent tools to keep a task list in its state.
ShellToolMiddlewareRuns shell commands under an execution policy (HostExecutionPolicy, DockerExecutionPolicy, CodexSandboxExecutionPolicy), with RedactionRule.
FilesystemFileSearchMiddlewareGives the agent scoped glob and content search over files.

On this page