tinker_cookbook.tool_use.build_agent_tool_env

tinker_cookbook.tool_use.build_agent_tool_env( renderer, tools, initial_messages, reward_fn, rollout_config, model_name, max_turns, failed_parse_reward, terminate_on_parse_error, max_tool_calls, max_trajectory_tokens, max_generation_tokens, context_overflow_reward, terminate_on_length, parse_error_policy)

Convenience method to build an EnvFromMessageEnv for tool-using agents.

The primary configuration surface is rollout_config: one composite ~tinker_cookbook.rl.rollout_presets.RolloutConfig (e.g. from ~tinker_cookbook.rl.rollout_presets.simple or ~tinker_cookbook.rl.rollout_presets.agentic) that drives the env-side knobs here, the runner-side budgets when the same config is passed to run_rollout, and the reward semantics when its termination is passed to do_group_rollout. The individual keyword arguments below remain supported; where both are given, the explicit keyword wins.

Parameters:

• renderer ( Renderer) – The renderer for tokenizing messages.
• tools ( list[ Tool ]) – List of tools the agent can call (must implement Tool protocol).
• initial_messages ( list[ Message ]) – Initial conversation history (system prompt, user message, etc.).
• reward_fn ( RewardFn) – Function that grades a completed episode. Takes the message history and returns (reward, metrics). Called once at episode end. Receives the full history by default; with a rollout_config whose termination policy is set, it receives only the completion suffix (messages generated during the rollout) unless pass_all_messages_to_grader is True, and is bounded by grader_timeout_seconds when set.
• rollout_config ( RolloutConfig | None) – Composite rollout configuration. Applies the env-side
• model_name ( str | None) – The model this env will run against. When set and rollout_config is not, the model's default configuration applies (~tinker_cookbook.rl.rollout_presets.default_rollout_config_for_model: thinkingmachines/Inkling defaults to ~tinker_cookbook.rl.rollout_presets.agentic). Pass rollout_config=simple() to opt out of a model default.
• max_turns ( int | None) – Maximum turns before episode ends. Default None means rollout_config.limits.max_turns when set, else 5.
• failed_parse_reward ( float) – Reward when model output fails to parse. Applied both when the renderer cannot parse the response and when a turn's tool calls are all malformed (unparsed_tool_calls).
• terminate_on_parse_error ( bool) – Whether a parse failure ends the episode. Defaults to True.
• max_tool_calls ( int | None) – Maximum tool calls per episode (checked pre-dispatch and mid-batch; the episode ends with StopReason.MAX_TOOL_CALLS). Default None = no cap. A rollout runner configured with RolloutLimits.max_tool_calls also sets this (the tighter cap wins).
• max_trajectory_tokens ( int | None) – Maximum tokens in trajectory before terminating episode.
• max_generation_tokens ( int | None) – Maximum tokens per generation. When set, the episode terminates if the trajectory + generation budget would exceed max_trajectory_tokens, preventing context overflow errors.
• context_overflow_reward ( float) – Reward assigned when the episode is terminated due to context overflow. Defaults to -0.1.
• terminate_on_length ( bool | None) – Whether a per-turn sampler "length" stop ends the episode. Set False (LENGTH-continue) to keep the truncated turn and continue — intended for use with a rollout runner enforcing cumulative token budgets via RolloutLimits, which is then what bounds the episode. Default None resolves to False when rollout_config configures a cumulative token budget (the runner owns LENGTH handling), else True (the default).
• parse_error_policy ( ParseErrorPolicy | None) – Optional ParseErrorPolicy governing parse failures. When set, it supersedes the one-shot failed_parse_reward / terminate_on_parse_error semantics for parse-error turns: structural failures (broken framing) stop immediately with StopReason.PARSE_ERROR; content failures (unparsable tool calls) are retried with an injected corrective message up to max_consecutive times. Default None keeps those one-shot semantics. A rollout runner configured with a policy also sets this via set_parse_error_policy.

Returns: An EnvFromMessageEnv ready for RL training.