CodeModeAgent module

`CodeModeAgent`

Bases: Module

A code-mode agent that reasons by writing and executing Python.

Instead of emitting JSON tool calls, the language model writes a Python snippet each turn. The snippet runs in a persistent Monty <https://github.com/pydantic/monty>_ REPL sandbox, variables, imports and function definitions accumulate across turns, so the agent can build up intermediate values, probe data and iterate.

Bound tools (if any) appear inside the sandbox as global async callables; scripts must await them inside an async def and drive with asyncio.run(...). See CodeStep.python_code description for the full Monty constraint list (supported stdlib, no classes, etc.).

Termination: the LM calls the always-present submit tool with the final payload. If max_iterations is reached without submit, a final inference step formats the accumulated trajectory into the target schema / data_model. Empty python_code snippets are no longer treated as a graceful exit, the loop feeds back a reminder and keeps going.

Example:

import synalinks
import asyncio

class Query(synalinks.DataModel):
    query: str

class Answer(synalinks.DataModel):
    answer: str

async def web_search(query: str) -> list:
    """Search the web.

    Args:
        query (str): the search query.
    """
    ...  # real implementation

async def main():
    language_model = synalinks.LanguageModel(model="ollama/mistral")
    inputs = synalinks.Input(data_model=Query)
    outputs = await synalinks.CodeModeAgent(
        data_model=Answer,
        language_model=language_model,
        tools=[synalinks.Tool(web_search)],
        max_iterations=5,
    )(inputs)
    agent = synalinks.Program(inputs=inputs, outputs=outputs)

    result = await agent(Query(query="Who discovered penicillin?"))
    print(result.prettify_json())

if __name__ == "__main__":
    asyncio.run(main())

Parameters:

Name	Type	Description	Default
`schema`	`dict`	Optional. The target JSON schema for the final structured answer. If not provided, use `data_model` to infer it. When both are omitted, the agent runs in schemaless mode, the final generator emits a `ChatMessage` that is appended to the trajectory, and `call` returns the `ChatMessages` trajectory directly (mirroring `FunctionCallingAgent`'s schemaless behaviour).	`None`
`data_model`	`DataModel \| SymbolicDataModel \| JsonDataModel`	Optional. The target data model for the final answer.	`None`
`language_model`	`LanguageModel`	The language model driving per-turn code generation and the final answer formatting.	`None`
`tools`	`list`	Optional. A list of `Tool` (or MCP tools) exposed to the sandbox as global async callables. Passing `None` means the agent reasons purely via code (no host callbacks). Naming gotcha: each tool is registered under `tool.name == tool._func.__name__`. `Tool(_my_helper)` shows up inside the script as `_my_helper`. Rename the function rather than relying on an alias.	`None`
`prompt_template`	`str`	Optional. Prompt template forwarded to the per-turn code generator.	`None`
`examples`	`list`	Optional. Examples forwarded to the per-turn code generator.	`None`
`instructions`	`str`	Optional. Instructions for the per-turn code generator. Defaults to `get_default_instructions()`.	`None`
`final_instructions`	`str`	Optional. Instructions for the final answer generator. Defaults to `instructions`.	`None`
`temperature`	`float`	Optional. Sampling temperature (Default 0.0).	`0.0`
`use_inputs_schema`	`bool`	Optional. Feed the input schema to the generator prompt (Default False).	`False`
`use_outputs_schema`	`bool`	Optional. Feed the output schema to the generator prompt (Default False).	`False`
`reasoning_effort`	`str`	Optional. One of 'minimal', 'low', 'medium', 'high', 'disable', 'none', None. Default None.	`None`
`use_chain_of_thought`	`bool`	Optional. Wrap the per-turn generator in ChainOfThought so it emits a `thinking` field alongside `code`. Default False.	`False`
`autonomous`	`bool`	Optional. If True (default), run the full code/execute/observe loop until the LM emits empty `code` or `max_iterations` is reached, then produce a structured final answer. If False, require a `ChatMessages` input and execute a single code turn per call, returning the updated trajectory, suitable for human-in-the-loop use. For cross-call REPL state in interactive mode, hand a `Sandbox` to `call` via the `sandbox` kwarg; the agent itself stays stateless.	`True`
`timeout`	`int`	Per-turn execution budget in seconds (Default 5). Each snippet must finish within this budget; exceeding it turns into an observation so the LM can recover on the next turn.	`5`
`max_iterations`	`int`	Maximum number of code-execution turns before forcing the final answer step (Default 5).	`5`
`max_output_chars`	`int`	Maximum characters to include from REPL output in the per-turn observation (Default 10_000). Anything beyond is truncated with a `… (truncated, N chars omitted)` marker so a single noisy turn cannot blow up the trajectory.	`10000`
`return_inputs_with_trajectory`	`bool`	Optional. Whether to return the full trajectory alongside the final answer (Default True).	`True`
`sandbox_type`	`type`	Optional. The `Sandbox` subclass to instantiate when no caller-supplied sandbox is passed to `call()`. Defaults to `MontySandbox`. Any `Sandbox` subclass whose `__init__` accepts `(timeout=..., name=...)` works; register custom subclasses with `@register_synalinks_serializable` so they round-trip through `get_config` / `from_config`.	`None`
`name`	`str`	Optional. The name of the module.	`None`
`description`	`str`	Optional. The description of the module.	`None`