LeafMesh Agent Configuration — Complete Field Reference

This document lists every configuration field, its type, default value, and accepted values. Use this to build frontend forms, dropdowns, and validation.

---

Table of Contents

1. Agent Types
2. AgentConfig — Core Fields (All Types)
3. LLM Agent Fields
4. Human Agent Fields
5. External Agent Fields
6. Programmatic Agent Fields
7. WebhookConfig
8. ChannelConfig
9. Memory Config
10. EscalationConfig
11. EscalationTarget
12. BrokerConfig
13. EventListener
14. Top-Level Config (LeafMeshConfig)
15. ManagerConfig
16. MeshConfig & Cloud Providers
17. Store (.env, not YAML)
18. EvolutionConfig
19. DataStructure
20. Entry Points
21. Validation Rules
22. Field Applicability by Agent Type

---

Agent Types

---

AgentConfig — Core Fields (All Types)

These fields apply to every agent regardless of agent_type.

Per-caller Response Overrides

communication_type sets one default response behavior for the whole agent — once dual, it replies back to every caller; once chain, never. Real workflows often need different behavior per caller: a sales agent might want to reply back to a customer-facing router (dual) but stay silent when an internal processor calls it (chain).

response_overrides is an optional per-caller override on top of communication_type. Lookup priority at the dual-callback site:

1. If response_overrides[called_by] is set → use that type.
2. Otherwise → fall back to communication_type.

External entry points (mesh_call from the outside, event listeners, scheduler wake_up) have no called_by and skip this lookup entirely — they always use the top-level communication_type. The override surface is internal-call-only by design.

List form (mirrors can_call style — recommended for YAML readability):

Dict form (also accepted, terser):

Both shapes behave identically at runtime.

Studio UI: the agent inspector exposes a "Per-caller overrides" panel under the Communication field. The caller dropdown is restricted to agents whose can_call actually targets this agent — overrides for unrelated agents would be dead config and never fire. When nobody calls this agent AND no overrides are configured, the panel hides entirely.

Available since: SDK v2.2.32 (field + runtime), v2.2.33 (API exposure + Studio panel).

Yields Enforcement

enforce_yields and enforce_yields_retry work together to make yields: an enforceable contract on the producer side, without coupling agents to each other's shapes.

Default behavior (enforce_yields: false) — lenient mode, backwards-compatible:

• Missing yield keys → filled with type defaults ("", 0, [], {}, false).
• Type mismatches → kept verbatim, WARNING logged.
• can_call conditions evaluate on a known shape (no more silent skips on undefined keys).

Strict mode (enforce_yields: true) — for production-critical agents:

• On contract violation, the SDK fires a Manager-driven retry.
• Up to enforce_yields_retry attempts. Each retry sees the previous (wrong) output + validation errors as rerun context:
  • LLM agents — the prompt appends a correction note.
  • Human agents — outbound payload exposes the rerun context; inbox/channel UI surfaces what's needed.
  • External connectors — data._rerun_context is added to the workflow payload.
  • Programmatic agents — input_data._rerun_context is available alongside the (possibly auto-corrected) inputs.
• After the retry budget is exhausted, fires AGENT_ERROR with error_type="YieldContractFailure" + retry_exhausted=true. Routes through manager.escalation: if configured.

Example:

Programmatic agents are retryable too — the Manager's analysis pass can inspect the failure and produce a corrected_input (e.g. fix "ORGANIZATION" → "Organization"). The retry runs the same deterministic function with the corrected input and produces a different result. See Manager — Rerun Flow for the full path.

Dynamic Per-Call Routing (Human Agents)

YAML configures default routing for a human agent — operator_ids: [alice, bob] lists who can see HITL requests, channels.slack.post_channel: "C0SLACK0123" sets the default Slack channel, etc. Real workflows need per-turn dynamism on top: "today's on-call is Alice," "this approval goes to the legal team's WhatsApp," "escalations route to the manager directly."

Routing has two layers. YAML is the contract (sane defaults, channel-scoped operator rosters). Pre-compose is the override (per-turn steering). They work together: pre-compose narrows when your code knows better; YAML catches anything pre-compose didn't set.

Layer 1 — YAML defaults

Operators live inside each channel that knows them. Slack owns Slack IDs, WhatsApp owns phone numbers, email owns addresses — the same logical roster (operator_ids: [alice, bob, carol]) is resolved per-channel via that channel's own operators: map.

Why channel-scoped? Each channel naturally owns the recipients it can address. Adding Slack → list its operators once inside the slack block. Removing WhatsApp → all its operator info goes with it (no orphans). You never spread a single recipient ID across two YAML sections.

Layer 2 — Pre-compose runtime override

Pre-compose populates reserved keys in input_data. Underscore prefix marks them as routing metadata (not business fields). Same convention as the existing _operator_ids.

Layer 2 — Example: daily on-call rotation

If the agent has Slack + WhatsApp + Email configured, the same _target_operator: "alice" routes to all three — alice's Slack DM, alice's WhatsApp number, alice's email — each pulled from its own channel's operators: map. You think in terms of people; each channel resolves to its own recipient namespace.

Resolution order (per outbound dispatch)

For each configured channel:

1. _target_channel_id (raw override — power user / dynamic ID)
2. _target_operator → channels.<provider>.operators[operator] (ergonomic)
3. adapter.get_channel_for_session(session_id) (reply continuity — the channel the inbound message arrived from)
4. adapter.config["post_channel"] (YAML default)

For the webhook fallback path:

1. _target_webhook_url (raw)
2. webhook_config.operators[operator] (ergonomic)
3. The webhook_config record's address (default)

Fail-soft semantics: if _target_operator is set but the operator has no entry under a given channel's operators: map, the SDK logs a WARNING and falls through to (3)/(4) for that channel. Messages are never silently dropped — there's always a YAML default to catch the fallback.

When to use which layer

Applies to all human-agent transports

Note for LLM, programmatic, external agents: The _target_* convention applies only to human agents (which actually route messages to people). LLM agents have no recipient. Programmatic / external agents route via their own connector_config (Zapier action, MCP tool, framework endpoint) — pre_compose can shape that payload via standard input_data fields, but the operator abstraction is human-specific.

Available since SDK v2.2.44. Backward compatible — agents not using the new keys behave exactly as before.

Conversation History Opt-In

LLM agents automatically receive prior conversation turns in their prompt. Programmatic, human, and external agents do not — they're stateless by design. When you want a non-LLM agent to see history (for e.g. domain-specific summarisation, context-aware retrieval), set the flag and the SDK injects the last history_limit turns at a standard location.

Where the history lands per agent type:

Human agent backwards compatibility: Human agents that have NOT opted in still use the pre-v2.2.1 hardcoded cap of 5 turns (preserves legacy webhook behaviour). Flip receive_conversation_history: true to switch to history_limit (default 20).

Studio + Playground UI: Both Studio's "Inputs & Outputs" panel and Playground's agent inspector expose a toggle for receive_conversation_history and a number input for history_limit — visible only when agent_type is non-LLM.

Streaming Output

Dual-mode LLM agents (the default LLM type) can stream their output token-by-token to the caller via Server-Sent Events. The caller passes stream=True to mesh_call, the SDK opens an SSE connection, and tokens flow out as they're generated.

Chunk envelope — three kinds: token (incremental text), final (assembled response dict at the end), error (terminal failure).

Auto-pick rule: If the agent declares exactly ONE yield key, stream_yield can be omitted and the SDK auto-picks that key. If the agent has multiple yields, set stream_yield explicitly.

Falls back cleanly: Non-dual-mode agents (communication_type: chain, execute) and non-LLM agents ignore the stream flag and return the full result as a single final chunk. Your SSE consumer code stays identical.

API surface: POST /api/mesh/request honours stream=true. Studio's Test Modal has a single toggle to enable streaming for debugging.

Accessing Yields in can_call Conditions

can_call.condition expressions read from the agent's parsed yields. Whatever shape your yields produce is what the condition sees.

Flat yields → top-level access

Nested object yield → dot-path access

For this pattern, the condition qualification.match_score >= 30 reads the nested field. Both forms are valid — pick whichever matches how your LLM (or programmatic function) naturally produces output.

Auto-wrap: flat LLM output under a single object yield

LLM prompts often ask for a flat JSON shape (top-level fields), even when the YAML declares yields: { something: object }. A common case:

The LLM does what the prompt asks — returns {match_score: 65, recommendation: "...", ...} at the top level, without a qualification: wrapper.

When all three conditions hold, the SDK reads the customer's intent and treats the whole flat dict as the value of that single yield, so qualification.match_score >= 30 works:

Result: qualification = {match_score: 65, recommendation: "...", summary: "..."} — accessible via dot-path in conditions.

This rule does not fire when:

• Multiple yields are declared (ambiguous — which one would the flat dict belong to?)
• The single yield is a scalar (string, number, boolean, list)
• The result already contains the yield key (already wrapped — passes through unchanged)
• The result is empty {} (treated as "missing", same as before)

If you want explicit nesting end-to-end, change your prompt to wrap:

Both forms now produce the same qualification yield, so existing configurations don't need to change.

Common gotchas

See Message Routing — Condition Evaluation for the full operator reference.

Changing agent_type

You can change an agent's type from Studio's Studio tab (per-agent editor). When agent_type changes, LeafMesh automatically removes fields that don't belong to the new type:

This prevents stale configuration from the old type interfering with the new type's execution.

yields and inputs Type Strings

Values can be a simple type string (flat field) or a nested object definition.

Flat fields — value is a type string:

Nested fields — value is an object with type and fields:

When a field uses the nested format, the frontend renders individual sub-field editors instead of a single text input. This is useful for external framework integrations (Composio, Zapier, etc.) where the request body has a known structure.

wait_for Expression Syntax

can_call Format

Narration Routing

narration is an agent-level field for routing hints you can't express as conditions. Conditions handle definitive routes ("if category is billing, call billing_agent"). Narration handles non-definitive routes ("if the customer sounds frustrated and mentions cancelling, maybe call retention_agent").

How it works:

1. Conditions are evaluated first by the control plane (AST, instant, deterministic)
2. Condition targets are dispatched immediately
3. The Manager's analysis pass reads the narration alongside the agent output
4. The Manager recommends additional next agents based on both condition results and narration hints
5. The Manager calls any narration-suggested agents that conditions didn't already dispatch

Key rules:

• Conditions are the authority — narration never overrides a condition result
• Narration targets are additive — they add to condition targets, never remove
• Narration can reference any agent in the mesh, not just those in can_call
• No narration = zero overhead
• If the Manager is disabled, narrations are ignored

See Manager — Narration Routing and Message Routing for the full flow.

Knowledge Config

knowledge enables RAG-powered context injection from a vector database. The agent gets both pre-call injection (automatic) and a query_knowledge tool (on-demand) — same dual pattern as memory.

Key points:

• Knowledge store and embedding credentials and addresses (connection strings, API keys, hosts) are entered only in the vault, under Infrastructure → Knowledge (MongoDB, pgvector, Pinecone), never in YAML
• When enabled, both retrieval paths are active automatically — no mode flag
• query_knowledge tool is stripped from agents without knowledge enabled
• The Manager can also have knowledge for SOP awareness (configured under manager.knowledge)

See Manager — Narration Routing for how knowledge integrates with Manager analysis.

---

LLM Agent Fields (agent_type: "llm")

These fields are used when agent_type is "llm". Ignored for other types.

LLM agents only. Tools and the tool blocks (zapier, composio, n8n, mcp), the playbook, follow-ups and their limits (schedule_followup, schedule_targets, max_followup_depth, max_followups_per_session), image output (output_modality, image_options), eager skills and the sandbox are refused at load on human, external and programmatic agents, and dropped when an agent's type changes.

Removed from agents: custom_endpoint and custom_headers. The model server and its headers are the mesh's setting — set them once in mesh.local. An agent that still has them loads with a warning, and they have no effect. The same goes for a per-agent kanban: block: the board is the mesh's (see Shared Board).

context_parts Keys

Each key is injected as a separate system message with a bracketed label, in the order below. Custom keys are also supported — they receive an auto-generated label from their name (MY_KEY → [MY KEY]).

Values are free text strings. All keys are optional — use any combination.

Model List

These are the models Studio's model picker offers as of SDK 2.4.436, plus the ones marked 2.4.508. Every key below can also be saved on the Infrastructure page instead of set as an environment variable.

OpenAI: (OPENAI_API_KEY)

• gpt-6-astra, gpt-6.1-sol, gpt-6.1-terra (2.4.508), gpt-6-sol, gpt-6-luna
• gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna
• gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini, gpt-5-nano
• gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini
• o3, o4-mini
• GPT-6, GPT-5.6 and the -pro models call tools through OpenAI's Responses API; LeafMesh switches to it automatically.

Anthropic: (ANTHROPIC_API_KEY)

• claude-fable-5-1, claude-fable-5
• claude-opus-5-5, claude-opus-5, claude-sonnet-5-5, claude-sonnet-5, claude-haiku-5-5
• claude-opus-4-8, claude-opus-4-7, claude-opus-4-6, claude-sonnet-4-6, claude-sonnet-4-5, claude-haiku-4-5

Google: (GOOGLE_API_KEY / GEMINI_API_KEY)

• gemini-4-argon, gemini-omni-1.2-flash (2.4.508)
• gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite
• gemini-3.1-pro-preview, gemini-3.1-flash-lite, gemini-3-flash-preview
• gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite

DeepSeek: (DEEPSEEK_API_KEY)

• deepseek-v4-pro, deepseek-flash
• Priced by time of day: calls in DeepSeek's busy hours cost twice the off-peak price. deepseek-chat and deepseek-reasoner are retired.

Mistral: (MISTRAL_API_KEY) (v2.2.25)

• mistral-large-4-0, mistral-medium-3-5-26-04, mistral-small-4-0-26-03, mistral-large-3-25-12
• codestral-2508
• Self-hosted: set MISTRAL_BASE_URL to override the default https://api.mistral.ai/v1 endpoint

xAI Grok: (XAI_API_KEY / GROK_API_KEY) (v2.2.25)

• grok-4.7, grok-4.6, grok-4.5, grok-4.3
• grok-4.20-0309-reasoning, grok-4.20-0309-non-reasoning, grok-build-0.1

Other model vendors (one key each; see LLM Providers → Other Model Vendors):

• By model name: kimi-k3, kimi-k3.1-pro, kimi-k3.1-pro-highspeed (Moonshot, MOONSHOT_API_KEY), qwen3.8-max / qwen3.7-plus / qwen3.7-flash (Alibaba, DASHSCOPE_API_KEY), glm-5.3 / glm-5.3-flash (Z.AI, ZAI_API_KEY), minimax-m3 / minimax-m3.1-flash (MINIMAX_API_KEY), mercury-3 (Inception, INCEPTION_API_KEY), muse-spark-1.3 / muse-wonder-1.0 (Meta, META_API_KEY), step-5-preview / step-3.7-flash (StepFun, STEPFUN_API_KEY), trinity-large-thinking (Arcee, ARCEE_API_KEY)
• Also by model name, using ids from the vendor's own list: Tencent Hunyuan (hy3…, hy4…, hunyuan-…, HUNYUAN_API_KEY), Xiaomi MiMo (mimo-…, MIMO_API_KEY), Upstage (solar-…, UPSTAGE_API_KEY), Reka (reka-…, REKA_API_KEY), Cohere (command-…, CO_API_KEY), Poolside (poolside/…, sent as written, POOLSIDE_API_KEY)
• By host prefix (removed before sending): openrouter/<lab>/<model> (OPENROUTER_API_KEY), groq/<model> (GROQ_API_KEY), cerebras/<model> (CEREBRAS_API_KEY)

Image models (for an agent with output_modality: image):

• OpenAI: gpt-image-2.6-flare, gpt-image-2.6-sunburst (2.4.508), gpt-image-2, gpt-image-1.5, gpt-image-1-mini (2.4.508), gpt-image-1, dall-e-3, dall-e-2
• Google: gemini-nano-banana-2.1 (2.4.508), gemini-3-pro-image, gemini-3.1-flash-image, gemini-2.5-flash-image
• Billed by kind of token (text, thinking, image in, image out) from the vendor's own counts (2.4.508)

AWS Bedrock:

• Any Bedrock model ID (e.g. anthropic.claude-sonnet-4-20250514-v1:0, amazon.titan-text-premier-v1:0)
• Requires mesh.bedrock config

Google Vertex AI:

• Any Vertex model ID (e.g. gemini-2.5-pro)
• Requires mesh.vertex config

Azure Foundry:

• Any Azure deployment name
• Requires mesh.foundry config

Local Models (vLLM, SGLang, Ollama, llama.cpp, etc.):

• Any model name supported by your local server
• Requires mesh.local config (or LOCAL_MODEL_ENDPOINT env var)
• See LocalModelConfig for server setup

thinking vs reasoning (v2.2.24+ semantics)

These are two separate features. The YAML key meanings were swapped in v2.2.24 to align with provider terminology — see LLM Agents → v2.2.24 migration.

You can use both together — thinking adds SDK reflection tools while reasoning enables the model's own native chain-of-thought.

Native Reasoning — Provider Support

Prompt Caching — Provider Support

Structured Output — Derived from yields

You do not declare a separate response_format field. The agent's yields schema is the single source of truth — at runtime the SDK auto-builds a provider-appropriate JSON enforcement shape from it.

If the LLM produces non-JSON or output that doesn't match the yields keys, the SDK runs one reflection retry; if that also fails, the agent returns a clean error instead of silently substituting defaults.

Example

---

Human Agent Fields (agent_type: "human")

These fields are used when agent_type is "human". is_human_powered is auto-set to true.

Removed in 2.4.382: approval is routing

require_human_confirmation, confirmation_seat and human_escalation_triggers no longer exist. A config that sets one of them on (true, a seat name, or a non-empty trigger list) is refused at load, because its author expected a person to see the work first. One that is off or empty is dropped, so old Studio defaults still load. To have a person approve work, route it to a human agent with can_call and a condition, and let that person's agent call the next one:

human_interface — Interface Types

Note: default mode writes the request to Redis and emits a stream event for an inbox UI to pick up — Studio renders this out of the box. If you're not running Studio, point webhook at your own service through an Outbound webhook record or use api with a Python callback instead.

Example — Default (Studio Frontend Inbox)

Example — Webhook with Channel Adapter

Two Scenarios for Human Agent Sessions

Human agents support two interaction patterns via the same webhook endpoint:

Scenario 1 — Resume (session_id present): When a POST to /webhook/{entry_point} includes a session_id that matches a pending HITL request, LeafMesh resumes that session. The operator's response is routed via can_call to the next agent.

Scenario 2 — New (no session_id or not found): When a POST has no session_id or the session has no pending request, LeafMesh creates a new workflow. If the human agent has no upstream caller, the operator's message is immediately routed via can_call — no HITL pending step is created.

---

External Agent Fields (agent_type: "external")

These fields are used when agent_type is "external".

| price_per_1k_tokens | float | null | ≥ 0 | no | For a platform that does not report what a call costs: the price per 1,000 tokens, so the mesh's estimate of each call has a cost and a monthly_cost_budget applies. Unset: only a token budget applies to an estimated agent. Also valid on a programmatic agent with an integration. See Per-Agent Budgets |

One agent = one action/workflow. Each agent targets one specific endpoint, graph, tool, or action. Create multiple agents with different connector_config values to call different workflows.

All connector_config fields can also be overridden per-call via request.connector_config at runtime.

Common connector_config fields (all frameworks)

connection (a vault connection name) is available on every connector type. after_handoff: wait and move_on are offered by n8n, Zapier and Lindy (and the phone-call platforms, which take only those two); every other framework takes reply only:

After the hand-off: reply, wait, move_on (2.4.508)

2.4.508 renamed mode: mode: sync → after_handoff: reply, mode: callback → after_handoff: wait. A configuration that still says mode is refused at load; a Python helper given mode= raises ValueError carrying the new line.

reply (default on n8n and Zapier): the connector POSTs to the external system and the HTTP response is the answer. Use it when the system returns the result in the same response.

wait and move_on: the connector POSTs with _leafmesh_callback_url and _leafmesh_session_id in the payload, and the agent's run ends at once — no worker is held. Its output is {"status": "waiting_for_callback" | "handed_off", "after_handoff", "agent", "framework", "message", "call_id"} (call_id only for phone-call platforms), and nothing routes on it. The hand-off is kept in the store and survives a restart. When the system POSTs the result to /callback/{agent_name}, the agent runs again with that answer as its output, and its can_call routes run on the answer. The difference is the board: wait keeps the step "asked, waiting"; move_on records the hand-off as done. Use them when:

• The external workflow takes longer than the HTTP timeout
• The external system answers later (e.g., n8n's "Respond Immediately" mode)
• You need the external system to process asynchronously and deliver results later

The webhook is signed, so it needs LEAFMESH_WEBHOOK_SECRET in .env (2.4.507: the mesh no longer derives one; webhooks answer 503 until it is set).

Python helpers always wait in place, because the code needs the answer. n8n() and zapier() take after_handoff="reply" (default) or "wait"; mcp() and composio() take "reply" only, and the mesh refuses "wait" for them at load. "move_on" adds nothing there. callback_timeout= keeps its name.

How external systems use callbacks:

The LeafMesh connector injects these fields into the outbound payload:

• _leafmesh_callback_url — the URL to POST the result back to
• _leafmesh_session_id — the session ID to include in the callback

The external system should POST to _leafmesh_callback_url with a JSON body containing:

connector_config fields per framework

From 2.4.481 every field typed record below (addresses — endpoint, url, webhook_url, base_url, mcp_endpoint — and credentials — api_key, user_api_key, auth_token, mcp_key, headers) is entered only in the vault. Make the record under Infrastructure → External agents → the framework (Zapier, n8n, Composio and MCP are under Infrastructure → Integrations), and name it with connection: (Zapier: vault_connection:). A record field written inline in connector_config, including an ${ENV} reference, is refused at load, and the error names the field and the record to create.

crewai

langgraph

autogen

Connects to an external AutoGen Studio or custom AutoGen API service via HTTP.

a2a

mcp

MCP supports two transport modes. tool_name is always required.

Common fields (both transports):

stdio transport fields:

http transport fields:

zapier

Tool name is built as {connection}_{action} (e.g. google_sheets_create_row).

*At least one of connection or action required for the tool name.

Zapier retired AI Actions, the REST API that api_key reached. A Zapier agent with only an api_key fails with that explanation; prefer_mcp and instructions are no longer read.

composio

n8n

n8n webhook URL types:

• Production: https://your-instance.app.n8n.cloud/webhook/<id> — works when workflow is activated (toggle ON)
• Test: https://your-instance.app.n8n.cloud/webhook-test/<id> — only works while n8n editor has "Listen for Test Event" active (one-shot, for development only)

n8n + after_handoff: wait:

With after_handoff: "wait" (or "move_on"), the n8n workflow should:

1. Start with a Webhook trigger node (receives the payload including _leafmesh_callback_url)
2. Configure the Webhook node to "Respond Immediately" (optional — reply works too)
3. Process the workflow
4. End with an HTTP Request node that POSTs back to {{ $json._leafmesh_callback_url }} with body:
   { "session_id": "{{ $json._leafmesh_session_id }}", "result": { ... } }

Phone-call platforms (2.4.508)

elevenlabs_agents, vapi, retell and bland: the platform makes the phone call and the outcome comes back by webhook. The agent's input carries phone_number (E.164, e.g. +14155550100); its other text, number and yes/no fields become the call's variables. Set the platform's webhook address to <mesh>/callback/calls/<framework> (signed, so it needs LEAFMESH_WEBHOOK_SECRET). The account's key, webhook signing secret and account ids come from connection.

See External Frameworks → Phone-call platforms.

---

Programmatic Agent Fields (agent_type: "programmatic")

These fields are used when agent_type is "programmatic".

Validation rule: integration is only valid when agent_type is "programmatic".

When integration is set, connector_config is passed as **kwargs to the connector's __init__. Use the same fields as the matching framework in the tables above (zapier → zapier fields, mcp → mcp fields, etc.).

The common fields (after_handoff, callback_timeout) are also available here (2.4.508; mode is refused at load). Use reply or wait.

---

WebhookConfig

Used inside webhook_config for human agents. A seat that needs no webhook is an Inbox seat: human_interface: default (no webhook or channel needed).

The webhook's address (base URL), header and query rows, and the inbound_token secret are an Add custom record on Studio's Infrastructure page with service type Outbound webhook. webhook_config names it with connection:. From 2.4.481 outbound_url, outbound_headers and inbound_auth_token written inline are refused at load.

The full shape: webhook_config: {connection: <name>, outbound_timeout: 30, inbound_endpoint: /path, response_mapping: {}, max_retries: 3, retry_delay: 5, operators: {}}. There is no method field.

---

ChannelConfig

Used inside channels dict for human agents. Keys are provider names.

Supported Provider Keys

Fields Per Channel

Each channel's credentials are a record under Infrastructure → Messaging (Slack, Microsoft Teams, Telegram, Zoho Cliq; Discord and WhatsApp coming); email under Infrastructure → Workspace → Email. The channel names it with connection:. Tokens and secrets written inline, including ${ENV} references, are refused at load (the connection name itself may come from the environment: connection: "${SLACK_CONNECTION:slack-workspace}" is fine).

On the record, never in YAML: tokens and secrets, addresses (url, base_url, api_base, endpoint, service_url, webhook_url, execution_url, accounts_url), storage_url, smtp_host / smtp_port / smtp_username, client_id, app_id, tenant_id and aws_access_key_id. inbound_domain, from_address and post_channel stay in YAML.

Note: ChannelConfig allows extra fields (extra="allow") for any provider-specific config.

Per-Provider Field Semantics

Inbound Route Registered Per Provider

Example

---

Email Channel

The email provider has a strict schema (validated at YAML load time, not at first send). Inbound is webhook-based via Mailgun / SendGrid / Postmark; outbound is SMTP via aiosmtplib.

EmailAttachmentConfig (under channels.email.attachments):

Provider-specific signing notes:

Inbound route: POST /channels/email/{agent_name}/{provider}/inbound

Required when enabled: the record's SMTP host and from_address must be set. Set enabled: false to register the block without configuring outbound.

Example:

See Human Agents — Email Channel for end-to-end setup walkthroughs per provider.

---

Memory Config

Field: memory — accepts bool or dict.

Simple Mode

Advanced Mode (Dict)

Example

---

EscalationConfig

Used inside manager.escalation.

auto_escalate Fields

---

EscalationTarget

Each target in the escalation.targets list. A webhook target's address, headers and token are an Outbound webhook record (an Add custom record on Studio's Infrastructure page); the target names it with connection:. A url or headers written inline is refused at load. The simplest escalation is to an Inbox seat (human_interface: default): targets: [{type: human_agent, agent: <seat>}].

Example

---

BrokerConfig

Top-level brokers: is a registry of connections to external event sources. An agent's listen_events: references a broker by name. One broker connection serves any number of listeners on different topics/queues — same way Knative Brokers, Dapr Components, and Azure Functions Connection= work.

From 2.4.481 a broker's addresses and credentials are entered only in the vault: make the record under Infrastructure → Brokers & queues (Redis Streams, MQTT, Apache Kafka, AWS SQS or IMAP Mailbox) and name it with connection:. The fields marked record below are set on that record; written inline in YAML they are refused at load.

The type discriminator selects the schema. Each subtype has its own field set — typos and wrong types fail at SDK startup, not at first message.

KafkaBrokerConfig (type: "kafka")

SQSBrokerConfig (type: "sqs")

MQTTBrokerConfig (type: "mqtt")

RedisStreamsBrokerConfig (type: "redis_streams")

Distinct from the SDK's primary Redis (used for sessions/yields/feed). Use this when an upstream service writes events into a Redis stream that an agent should consume.

IMAPBrokerConfig (type: "imap")

For email-as-event-source when webhook-based email isn't viable (firewall, no public DNS). For webhook-based email channels on human agents, use channels.email instead.

---

EventListener

A single entry in an agent's listen_events:. Each entry creates one long-lived asyncio task that consumes from the named broker and dispatches matching messages into the mesh as an entry-point event for the agent. All listeners use at-least-once delivery with idempotency keying on (listener_name, message_id) to prevent double-processing on retry.

EventDeliverySpec

DeadLetterRef

Points at another broker (by name) and the destination shape on it. Only one of topic/queue/stream is meaningful per broker type — the listener validates the right one is set at startup.

How Listeners Fire Agents

When a message arrives:

1. Verify — the listener verifies the source-specific signature/credentials at the connection layer.
2. Filter — filter: keys are matched against the normalized envelope. Non-match = ack and skip (no retry).
3. Idempotency — the runtime tracks (listener_name, message_id) to drop duplicate deliveries. If already processed, ack and skip.
4. Deserialize — if deserialize: is set, payload is validated through the named Pydantic class. ValidationError → DLQ (no retry — bad data won't fix itself).
5. Wrap — message is wrapped in a CloudEvents-shaped TriggerEvent envelope.
6. Dispatch — published as an ENTRY_POINT event for the agent. Same path as a POST /webhook/{entry_point}. Agent counts toward invocation metering like any other invocation.
7. Ack — on success, the source is acked (Kafka offset commit, SQS DeleteMessage, Redis XACK, etc.).
8. Retry / DLQ — on failure, the message is retried per delivery.backoff until max_attempts, then routed to dead_letter if configured.

See Event Listeners — Architecture for an end-to-end walkthrough.

---

Top-Level Config (LeafMeshConfig)

Note: LeafMeshConfig has extra="forbid" — unknown top-level keys will raise a validation error.

From 2.4.482 the store is not a YAML setting: persistence: and top-level redis: blocks are no longer read (LeafMesh logs a warning at boot). Set the store in .env; see Store.

---

ManagerConfig

manager.prompt — Evaluation Criteria

Gives the Manager direct context about your mesh's specific purpose, success criteria, and escalation triggers. The Manager reads this on every agent turn alongside its domain guidance.

routing Fields

The four rule sets below live directly under manager: (for example manager.timeout_rules), never under manager.coordination_rules:. From 2.4.482 a file that still nests them there is moved at load, with a warning.

human_input_rules (Defaults)

timeout_rules (Defaults)

workflow_pause_rules (Defaults)

human_response_rules (Defaults)

The scenario keys name the kind of reply a human agent sent (type on the response). They decide whether the manager reviews or escalates after that reply; they are not an approval step. Approval itself is routing — see the removed-fields note under Human Agent Fields above.

---

MeshConfig & Cloud Providers

MeshConfig

mesh.call_timeout is gone. The default mesh call timeout is timeouts.mesh_call_default_timeout_s (default 300 seconds); from 2.4.482 an old mesh.call_timeout is moved there at load, with a warning.

From 2.4.481 the address and credentials of bedrock, vertex, foundry and local are entered only in the vault, under Infrastructure → Models (a local server under Models → Local / self-hosted); each block names its record with connection:. Fields typed record below are set on that record; written inline they are refused at load. Model keys and LOCAL_MODEL_ENDPOINT in .env still work: a value in .env wins, and the vault fills any gaps.

BedrockConfig (AWS)

Auth: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY env vars, IAM role, or ~/.aws/credentials

VertexConfig (Google Cloud)

Auth: GOOGLE_APPLICATION_CREDENTIALS env var or gcloud auth

FoundryConfig (Azure)

Auth: AZURE_FOUNDRY_API_KEY or AZURE_FOUNDRY_TOKEN env vars

LocalModelConfig

LOCAL_MODEL_ENDPOINT and LOCAL_MODEL_SERVER_TYPE are read from .env, or filled from a Local / self-hosted model record. A local model's request timeout is mesh.local.timeout (default 120 s). With no mesh.local block, the local model uses timeouts.llm_hard_timeout_s (default 90 s).

Supported servers and their endpoint + server_type:

Tip: Most production servers (vLLM, SGLang, TGI, llama.cpp) expose OpenAI-compatible endpoints. Use server_type: openai for all of them. If server_type is omitted, it's auto-detected from the URL.

---

Store (.env, not YAML)

From 2.4.482 the store is set only in .env. There is no persistence: or redis: block in the YAML.

Studio shows under Infrastructure → Datastores whether the store is reachable, its latency and server, the settings in force and which .env names set them; it never shows the address or password. See Persistence.

---

APIConfig

Top-level api: block Configures the LeafMesh HTTP server.

---

EvolutionConfig

evolution: and evolution_api: are current top-level YAML blocks. A new agency's YAML is written with these values:

Changing evolution_api.host, port or enabled needs a process restart; every other saved setting applies without one (from 2.4.484).

Operators kick off evolution runs from Studio with their test scenarios. See Evolutionary Optimization for what evolution does and how to use it.

---

DataStructure

---

Entry Points

Each entry point is a named portal into the mesh.

Example

---

Validation Rules

These are enforced at config load:

---

Field Applicability by Agent Type

Shows which fields are used (U), ignored (—), or required (R) for each agent type. thinking_budget is a deprecated alias: it is read as reasoning_budget, with a warning, and is not a field of its own.

Legend: R = required, U = used, — = ignored, auto = auto-set