Module agent 

Agent definitions, configuration, and completion API types.

An Agent is a fully-specified configuration of a single upstream language model. It encapsulates:

• Model identity (which LLM to use)
• Prompt structure (prefix/suffix messages)
• Decoding parameters (temperature, top_p, etc.)
• Provider preferences and routing
• Output mode, reasoning settings, and verbosity

Content-Addressed Identity

Agents use content-addressed identifiers - their ID is derived deterministically from their full definition using XXHash3-128. This ensures:

• Two identical definitions always produce the same ID
• IDs can be computed anywhere (server, client, browser via WASM)
• No hidden mutation or “latest version” ambiguity

Normalization

Before computing an ID, definitions are normalized via InlineAgentBase::prepare:

• Default values are removed (e.g., temperature: 1.0 becomes None)
• Empty collections are removed
• Collections are sorted for deterministic ordering

Modules

claude_agent_sdk

codex_sdk

completions

Agent completions request and response types.

laboratories

Functions for working with Laboratories.

mcp_servers

Functions for working with McpServers.

mock

openrouter

script

validate

Structs

AgentWithFallbacksWithCount

An AgentWithFallbacks with a count (post-validation swarm agent slot).

ClientObjectiveaiMcp

Client-side MCP surface the agent expects:

ClientObjectiveaiMcpEntry

A single owner / name / version reference identifying one tool inside ClientObjectiveaiMcp::tools. Plugin references use the larger ClientObjectiveaiMcpPluginEntry — they carry extra executable / mcp_servers fields tools don’t have.

ClientObjectiveaiMcpHeaders

Snapshot of the three transient X-OBJECTIVEAI-MCP-* request headers an HTTP caller stamps on its initial dial of the objectiveai-mcp proxy upstream.

ClientObjectiveaiMcpPluginEntry

Plugin reference inside ClientObjectiveaiMcp::plugins.

ClientObjectiveaiMcpPluginMcpServer

One mcp_servers entry on a ClientObjectiveaiMcpPluginEntry: the manifest-declared name the agent wants exposed, plus optional arguments the CLI feeds to the plugin alongside the name when bringing the server up. The arguments map is sorted by key in prepare so two equivalent declarations (same key/value pairs in any order) hash to the same canonical form.

InlineAgentBaseWithFallbacks

An InlineAgentBase with optional fallbacks (no description).

InlineAgentBaseWithFallbacksOrRemoteWithCount

An InlineAgentBaseWithFallbacksOrRemote with a count (pre-validation swarm agent slot).

InlineAgentWithFallbacks

A validated InlineAgent with optional fallbacks (no description).

Laboratory

A laboratory provisioned for an agent: the container spec the CLI conduit materializes on demand at MCP-initialize. No mounts — agent laboratories don’t support them.

McpServer

An MCP server that the agent can connect to.

RemoteAgent

A validated remote Agent with metadata and computed content-addressed ID.

RemoteAgentBase

A remote agent base definition with metadata.

RemoteAgentBaseWithFallbacks

A remote agent base definition with description and optional fallbacks.

RemoteAgentWithFallbacks

A validated remote agent with description and optional fallbacks.

Enums

Agent

A validated Agent, either remote (with metadata) or inline.

AgentBase

An Agent base definition, either remote (with metadata) or inline.

AgentWithFallbacks

A validated agent with optional fallbacks, either remote (with description) or inline.

Continuation

Continuation state for multi-turn agent completions.

InlineAgent

A validated inline Agent with its computed content-addressed ID.

InlineAgentBase

The base inline configuration for an Agent (without computed ID or metadata).

InlineAgentBaseWithFallbacksOrRemote

An agent specification that is either an inline agent base with fallbacks or a remote path reference.

InlineAgentBaseWithFallbacksOrRemoteCommitOptional

Like InlineAgentBaseWithFallbacksOrRemote but with optional commit. Used in request types where commit resolution happens server-side.

InlineAgentRef

A borrowed reference into an InlineAgentBase variant.

OutputMode

The method used to constrain LLM output to valid response keys.

Upstream

Supported agent upstreams.

Constants

AGENT_LABORATORY_ID_PREFIX

The reserved id namespace for agent laboratories. A laboratory whose id starts with this prefix is DERIVED from an agent (see laboratories::derived_id) — never user-created, never attachable or detachable.

Functions

prepare

Sorts plugins + tools for deterministic ordering. Per-plugin mcp_servers get their inner arguments IndexMap key-sorted in place, then the mcp_servers Vec is sorted via the ClientObjectiveaiMcpPluginMcpServer Ord impl. Collapses an all-empty struct to None so the enclosing Option can drop the empty container entirely (same convention as super::mcp_servers::prepare).

validate

Validates the configuration. Each entry’s fields must be non-empty, and the plugins / tools lists each contain no (owner, name, version) duplicates. Free-function counterpart to super::mcp_servers::validate.

Type Aliases

Laboratories

A list of agent laboratories.

McpServers

A list of MCP servers.