Code Mode
With code mode, the agent gets arun_code tool. Instead of calling tools one
at a time, one model step at a time, the model writes a short Python program
that calls them as functions, loops, filters and computes, and gets back the
program’s result and what it printed. Four lookups that would take four calls
take one.
Needs the
codemode extra. Every output on this page is what the code printed
when it was run; the program the model writes, and its wording, will differ on
your run.A program instead of four calls
run_code call (code_calls), with an ID of the form
<run_code call ID>.<n>, its arguments, its outcome and its own policy
decision.
The prompt says “Use run_code” to make the example certain; the model
decides for itself when a program is worth it, and still calls tools directly
when one call will do.
How it works
- What the model is told.
run_code’s description lists each tool the program may call as a Python signature with its description, and the limits. Tools are called like Python functions, with keyword arguments or in the order of their parameters; each returns the tool’s result data, or raises an error the program can catch. The value of the last expression is returned, with everything printed. - Where it runs. Programs run in Monty 1.x, Pydantic’s interpreter for a subset of Python, in a separate worker process. A program has no filesystem, network or environment access, and cannot sleep: an attempt raises an error inside the program. The clock and random numbers work. Third-party packages cannot be imported.
- Each tool call is a real tool call. It goes through the same path as a call the model makes: its arguments are checked against the schema, governance decides it (a denied call raises inside the program), the run’s record notes it before it starts, and it is traced.
- Limits. A program is stopped at its time limit, memory limit or tool-call limit, and its printed output is capped.
- Governance. Running a program is its own capability,
code.run. Theinteractive-devandpermissive-devprofiles allow it;strict-productionneeds a rule. Each tool the program calls is then decided on its own.
Options
Set underagent_config["code_mode"]:
Every other agent setting is in the
agent settings reference.
Approval inside a program
When a tool the program calls needs a person, the program pauses: it is stored, signed, on the run’s record, and the run waits like any other (Durable Runs). After the decision, the program continues from that call. Nothing it already did runs again..2), continued from there
after the approval, and paused again at the second (.3). Nothing before a
pause ran again: each order was refunded exactly once.
For a call made from a program,
approval["arguments"] holds the arguments
the program passed to that call ({'order_id': 'A1'} above), so the approver
sees what would run, as for a call the model made directly.snapshot_key (or
OMNICOREAGENT_CODE_SNAPSHOT_KEY) so a paused program can continue in another
process, such as after a restart, with a durable memory store. A stored
program that does not verify against the key is refused and never runs.
Without a key, a random one is made per process, so a paused program can
only continue in the process where it paused. A program too large to store
(max_snapshot_bytes) is told so instead of pausing, and can call the tool
directly.
When things go wrong
A program’s errors go back to the model as therun_code call’s error, so it
can fix the program and try again. These are the messages it gets.
code mode requires optional dependency 'pydantic_monty'
code mode requires optional dependency 'pydantic_monty'
The extra is not installed. The agent is created without complaint; the
first program fails with:Install it:
pip install "omnicoreagent[codemode]".ValueError: code_mode has unknown keys
ValueError: code_mode has unknown keys
Raised when the agent is created, for a misspelt key or a wrong value:
The program was stopped: it may make at most N tool calls
The program was stopped: it may make at most N tool calls
With Raise
max_tool_calls 3, a loop of ten calls ended with:max_tool_calls, or give the model a tool that does the batch in
one call.TimeoutError: feed time limit exceeded
TimeoutError: feed time limit exceeded
The program computed for longer than
max_duration_seconds (2 here):PermissionError, 'not supported in this environment', ModuleNotFoundError
PermissionError, 'not supported in this environment', ModuleNotFoundError
The program reached outside its sandbox. These come back as the
program’s traceback, ending in:This is the sandbox working. Give the program a tool for what it needs.
Next
Local tools
The functions a program calls.
Durable runs
Pause, approve, resume, and recover after a crash.
Security model
Policies, sandboxes, and what each one guarantees.
Read the trajectory
Every program and every call it made, on the record.