Struct AgentConfig 

pub struct AgentConfig {

    pub model: String,
    pub api_key: Option<String>,
    pub system_instructions: Option<SystemInstructions>,
    pub capabilities: Option<CapabilitiesConfig>,
    pub workspaces: Vec<PathBuf>,
    pub tools: Vec<ToolDefinition>,
    pub policies: Vec<PolicyRule>,
    pub triggers: Vec<TriggerEntry>,
    pub hooks: Vec<HookEntry>,
    pub skills: Vec<PathBuf>,
    pub mcp_servers: Vec<McpServer>,
    pub conversation_id: Option<String>,
    pub save_dir: Option<PathBuf>,
    pub app_data_dir: Option<PathBuf>,
    pub response_schema: Option<JsonSchema>,
    pub gemini: Option<GeminiConfig>,
    pub initial_history: Vec<ConversationMessage>,
    pub retry_config: Option<RetryConfig>,
}

Full configuration for creating an agent.

Covers model selection, system instructions, capabilities, tools, policies, hooks, MCP servers, structured output, and Gemini backend settings. All fields have sensible defaults.

Construction patterns

AgentConfig deliberately supports two construction paths:

1. TypedBuilder — ergonomic chained construction with impl IntoIterator setters for collection fields. Preferred for programmatic use:

   let config = AgentConfig::builder()
       .model("gemini-3.5-flash")
       .build();

2. Struct literal with ..Default::default() — convenient for deserialization (serde), config files, and framework code that already has fully-formed values:

   let config = AgentConfig {
       model: "gemini-3.5-flash".into(),
       ..AgentConfig::default()
   };

Both paths are supported intentionally. The builder provides ergonomic setters (e.g. accepting impl IntoIterator for collection fields), while struct literals enable direct field access for serialization roundtrips and downstream framework integration.

Fields

model: String

The model name (e.g. "gemini-3.5-flash").

api_key: Option<String>

API key. Falls back to GEMINI_API_KEY env var if None.

system_instructions: Option<SystemInstructions>

Optional system instructions (custom text or templated sections).

capabilities: Option<CapabilitiesConfig>

Agent capability toggles (tool lists, subagents, compaction).

workspaces: Vec<PathBuf>

Workspace directories the agent can access.

When empty (the default), the Python SDK’s own default of [os.getcwd()] applies. Set explicitly to override.

tools: Vec<ToolDefinition>

Custom tool definitions exposed to the agent.

policies: Vec<PolicyRule>

Policy rules evaluated before each tool call.

triggers: Vec<TriggerEntry>

Event-driven triggers attached to this agent.

hooks: Vec<HookEntry>

Lifecycle hooks (pre-turn, post-turn, pre-tool, etc.).

skills: Vec<PathBuf>

Paths to skill instruction files loaded into the agent.

Serializes as "skills_paths" to match the Python SDK field name.

mcp_servers: Vec<McpServer>

MCP server configurations.

conversation_id: Option<String>

Resume an existing conversation by its SDK id.

Set this to an id previously returned by AgentHandle::conversation_id to resume that conversation. The SDK (local harness) uses it as the trajectory cascade_id to reload, so it must reference a conversation already persisted under Self::save_dir; passing an unknown id fails agent startup with “conversation not found”.

Leave unset to start a fresh conversation — the harness assigns a new id, which is then observable via AgentHandle::conversation_id and custom-tool ToolContext.

save_dir: Option<PathBuf>

Directory where conversation state is saved.

app_data_dir: Option<PathBuf>

Application data directory.

response_schema: Option<JsonSchema>

Optional JSON schema for structured responses.

gemini: Option<GeminiConfig>

Gemini model backend configuration.

Controls per-model API keys, model selection per capability, and generation parameters such as thinking_level.

Serializes as "gemini_config" to match the Python SDK field name.

initial_history: Vec<ConversationMessage>

Optional initial conversation history to inject after agent creation.

When set, these messages are inserted into the SDK’s internal _history list before the first chat turn, enabling warm-start scenarios such as safety recovery (re-creating an agent with curated prior context).

Serialized as "initial_history" and consumed by the Python init script. Skipped from serialization when empty.

retry_config: Option<RetryConfig>

Optional retry configuration for API calls and model outputs.

Implementations

impl AgentConfig

pub fn builder() -> AgentConfigBuilder<((), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), ())>

Create a builder for building AgentConfig. On the builder, call .model(...)(optional), .api_key(...)(optional), .system_instructions(...)(optional), .capabilities(...)(optional), .workspaces(...)(optional), .tools(...)(optional), .policies(...)(optional), .triggers(...)(optional), .hooks(...)(optional), .skills(...)(optional), .mcp_servers(...)(optional), .conversation_id(...)(optional), .save_dir(...)(optional), .app_data_dir(...)(optional), .response_schema(...)(optional), .gemini(...)(optional), .initial_history(...)(optional), .retry_config(...)(optional) to set the values of the fields. Finally, call .build() to create the instance of AgentConfig.

impl AgentConfig

pub fn effective_api_key(&self) -> Option<String>

Resolve the effective API key using the same priority chain as the Python SDK’s LocalAgentConfig → _build_harness_config:

1. Per-model key (gemini.models.default.api_key)
2. Shared GeminiConfig key (gemini.api_key)
3. Top-level shorthand (api_key)
4. $GEMINI_API_KEY environment variable

pub fn custom_tool_names(&self) -> Vec<String>

Returns the names of all explicitly registered custom tools. To get the full list of tools including built-ins, combine this with capabilities.enabled_tools or examine tools + default semantics.

Trait Implementations

impl Clone for AgentConfig

fn clone(&self) -> AgentConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AgentConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AgentConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<AgentConfig> for LocalAgentConfig

fn from(agent: AgentConfig) -> Self

Converts to this type from the input type.

impl Serialize for AgentConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.