tinker_cookbook.tool_use.AgentToolMessageEnv

class tinker_cookbook.tool_use.AgentToolMessageEnv( MessageEnv)

Generic tool-use MessageEnv for agents.

Fields:

• tools ( list[ Tool ])
• initial_messages ( list[ Message ])
• max_turns ( int)
• reward_fn ( RewardFn)
• failed_parse_reward ( float, default: -0.1)
• terminate_on_parse_error ( bool, default: True)
• max_tool_calls ( int | None, default: None)
• parse_error_policy ( ParseErrorPolicy | None, default: None)
• tool_execution ( ToolExecution, default: 'parallel')
• termination_policy ( TerminationRewardPolicy | None, default: None)
• history ( list[ Message ], default: field(default_factory=list))

set_max_tool_calls( max_tool_calls)

Apply a rollout-level tool-call limit (seam used by the rollout runner).

When a limit is already configured on the env, the tighter cap wins.

Parameters:

• max_tool_calls ( int)

Returns: None

set_parse_error_policy( policy)

Apply a rollout-level parse-error policy (seam used by the rollout runner).

Parameters:

• policy ( ParseErrorPolicy)

Returns: None

observe_truncated_response( message)

Record a truncated assistant response (LENGTH-continue support).

The message is appended to the history as-is; no tools run and the turn/tool-call counters are untouched.

Parameters:

• message ( Message)

Returns: list[ Message ]

add_messages( messages)

Append externally injected messages (rollout-hook support).

Parameters:

• messages ( list[ Message ])

Returns: list[ Message ]

step( message)

Execute any tools and return next messages.

The episode ends when:

• no tool calls in message (model decided to stop)
• every tool call in the message failed to parse and terminate_on_parse_error is True
• a tool returns should_stop=True
• max_turns reached
• the tool-call budget (max_tool_calls, when configured) is exhausted — checked pre-dispatch and mid-batch, so a turn asking for more calls than the remaining budget executes only the allowed prefix and then stops

Tool calls whose arguments failed to parse (e.g. malformed JSON) arrive in message["unparsed_tool_calls"]. When the message contains only unparsed tool calls, the turn is a parse failure: failed_parse_reward is applied, metrics["parse_error"] is set, the error details are recorded in logs["parse_errors"], and reward_fn is skipped. When valid and unparsed tool calls are mixed, the valid ones execute and the episode proceeds normally with no failure reward (some tool progress happened), but the parse error is still surfaced via metrics["parse_error"] and logs["parse_errors"].

reward_fn is called once at episode end to grade the full trajectory.

Parameters:

• message ( Message)

Returns: MessageStepResult