Skip to main content

Code Mode

With code mode, the agent gets a run_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

One model step made four tool calls. Each is in the trajectory under its 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. The interactive-dev and permissive-dev profiles allow it; strict-production needs a rule. Each tool the program calls is then decided on its own.

Options

Set under agent_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.
The program paused at its first refund (call .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.
A denied call raises inside the program with the approver’s note, so the program can catch it and carry on. Across processes. Set 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 the run_code call’s error, so it can fix the program and try again. These are the messages it gets.
The extra is not installed. The agent is created without complaint; the first program fails with:
Install it: pip install "omnicoreagent[codemode]".
Raised when the agent is created, for a misspelt key or a wrong value:
With max_tool_calls 3, a loop of ten calls ended with:
Raise max_tool_calls, or give the model a tool that does the batch in one call.
The program computed for longer than max_duration_seconds (2 here):
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.