sofias-sdk-lite 0.2.0__tar.gz → 0.3.0__tar.gz

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sofias-sdk-lite
-Version: 0.2.0
+Version: 0.3.0
 Summary: Build agents on the Sofias agent graph and run them over RabbitMQ.
 Keywords: agents,ai,llm,rabbitmq,sofias
 Author: Sofias Tech, S.L.
@@ -56,6 +56,11 @@ Build multi-node agents on a declarative graph and run them against RabbitMQ.
   from the agent's settings or the `SOFIAS_LLM_*` environment. `create_llm()`
   builds the client when you need it explicitly; `LLMCallable` stays a protocol
   for anything the bundled clients do not cover.
+- **The user's connectors** — `McpToolProvider` turns the connectors the platform
+  sends with each turn (mail, documents, CRM, the company's own MCP servers…)
+  into tools for your LLM nodes. They go through the platform's intermediary:
+  your agent never sees a credential. See
+  [Using the user's connectors](https://docs.sofias.ai/guides/connectors/).
 
 Nothing here depends on a private backend or an internal config service.
 Where the model lives is deployment configuration, not agent code.
@@ -209,11 +214,11 @@ if __name__ == "__main__":
 
 ## Scope (v1)
 
-Core agent graph, RabbitMQ messaging, the runner, and LLM clients for the
-Sofias gateway / any OpenAI-compatible endpoint ship today. Memory and MCP
-tool discovery are intentionally out of scope for v1 — the SDK ships the
-relevant protocols (`MemoryProvider`, `ToolProvider`) so you can plug in
-your own, and these become optional extras in a later release.
+Core agent graph, RabbitMQ messaging, the runner, LLM clients for the Sofias
+gateway / any OpenAI-compatible endpoint and, since 0.3.0, the user's
+connectors (MCP) ship today. Memory is intentionally out of scope for v1 — the
+SDK ships the `MemoryProvider` protocol so you can plug in your own, and it
+becomes an optional extra in a later release.
 
 ## Source and contributions
 

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/README.md

@@ -20,6 +20,11 @@ Build multi-node agents on a declarative graph and run them against RabbitMQ.
   from the agent's settings or the `SOFIAS_LLM_*` environment. `create_llm()`
   builds the client when you need it explicitly; `LLMCallable` stays a protocol
   for anything the bundled clients do not cover.
+- **The user's connectors** — `McpToolProvider` turns the connectors the platform
+  sends with each turn (mail, documents, CRM, the company's own MCP servers…)
+  into tools for your LLM nodes. They go through the platform's intermediary:
+  your agent never sees a credential. See
+  [Using the user's connectors](https://docs.sofias.ai/guides/connectors/).
 
 Nothing here depends on a private backend or an internal config service.
 Where the model lives is deployment configuration, not agent code.
@@ -173,11 +178,11 @@ if __name__ == "__main__":
 
 ## Scope (v1)
 
-Core agent graph, RabbitMQ messaging, the runner, and LLM clients for the
-Sofias gateway / any OpenAI-compatible endpoint ship today. Memory and MCP
-tool discovery are intentionally out of scope for v1 — the SDK ships the
-relevant protocols (`MemoryProvider`, `ToolProvider`) so you can plug in
-your own, and these become optional extras in a later release.
+Core agent graph, RabbitMQ messaging, the runner, LLM clients for the Sofias
+gateway / any OpenAI-compatible endpoint and, since 0.3.0, the user's
+connectors (MCP) ship today. Memory is intentionally out of scope for v1 — the
+SDK ships the `MemoryProvider` protocol so you can plug in your own, and it
+becomes an optional extra in a later release.
 
 ## Source and contributions
 

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.2.0"
+version = "0.3.0"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sofias-sdk-lite"
-version = "0.2.0"
+version = "0.3.0"
 description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
 readme = "README.md"
 requires-python = ">=3.11"

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/agent/agent.py

@@ -67,12 +67,13 @@ class Agent:
     to Node instances which handle their own execution.
 
     Example:
+        ```python
         # Agent is typically built via AgentBuilder
         agent = (
             AgentBuilder("my_agent", version="1.0.0")
             .with_settings_class(MySettings)
             .with_contract(input_schema=MyInput, output_schema=MyOutput)
-            .add_node("start", node_config, contract)
+            .add_llm_node("start", node_config, contract)
             .set_entry_node("start")
             .set_terminal("start")
             .build()
@@ -86,6 +87,7 @@ class Agent:
             )
         )
         assert response.status == ResponseStatus.SUCCESS
+        ```
     """
 
     def __init__(

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/agent/agent_builder.py

@@ -64,6 +64,7 @@ class AgentBuilder:
     time, catching configuration errors before runtime.
 
     Example:
+        ```python
         agent = (
             AgentBuilder("inbox_assist", version="1.0.0")
             .with_description("Agent that processes incoming emails")
@@ -84,6 +85,7 @@ class AgentBuilder:
             .with_circuit_breaker(CircuitBreakerConfig(failure_threshold=5))
             .build()
         )
+        ```
     """
 
     def __init__(self, name: str, *, version: str = "1.0.0") -> None:
@@ -408,6 +410,7 @@ class AgentBuilder:
             Self for method chaining.
 
         Example:
+            ```python
             builder.with_delegation_transport(my_transport).add_delegation_node(
                 name="delegate_analysis",
                 config=DelegationNodeConfig(
@@ -424,6 +427,7 @@ class AgentBuilder:
                     "transform_for_analyzer": lambda d: {"text": d["content"]},
                 },
             )
+            ```
         """
         self._delegation_node_configs[name] = config
         self._delegation_node_contracts[name] = contract
@@ -709,6 +713,7 @@ class AgentBuilder:
             Self for method chaining.
 
         Example:
+            ```python
             from sofias_sdk_lite.state import (
                 ConversationState,
                 InMemoryStateProvider,
@@ -717,6 +722,7 @@ class AgentBuilder:
             builder.with_conversation_state(
                 ConversationState(InMemoryStateProvider())
             )
+            ```
         """
         self._conversation_state = state
         return self

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/agent/agent_config.py

@@ -47,6 +47,7 @@ class AgentConfig(BaseModel):
     three-level configuration resolution: SDK > Agent > Node.
 
     Example:
+        ```python
         config = AgentConfig(
             name="inbox-assistant",
             version="1.0.0",
@@ -56,6 +57,7 @@ class AgentConfig(BaseModel):
             settings_class=InboxAssistantSettings,
             llm=AgentLLMConfig(model="gpt-4o"),
         )
+        ```
     """
 
     model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/agent/middleware.py

@@ -4,7 +4,8 @@ Middleware hooks are called before and after each node execution,
 allowing logging, metrics, tracing, and input/output transformation
 without modifying node code.
 
-Example::
+Example:
+    ```python
 
     class MetricsMiddleware:
         async def before_node(self, node_name, input_data):
@@ -24,6 +25,7 @@ Example::
         .with_middleware(MetricsMiddleware())
         .build()
     )
+    ```
 """
 
 from __future__ import annotations

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/agent/response_workflow.py

@@ -21,6 +21,7 @@ This module is transport-agnostic: it has no dependency on any specific
 message broker. Wire it to whatever transport your application uses.
 
 Example:
+    ```python
     class MyRabbitMQWorkflow:
         async def send_response(
             self,
@@ -38,6 +39,7 @@ Example:
         .with_response_workflow(MyRabbitMQWorkflow())
         .build()
     )
+    ```
 """
 
 from __future__ import annotations
@@ -99,6 +101,7 @@ class StreamingResponseWorkflow(Protocol):
     send_response() is still called at the end with the complete response.
 
     Example:
+        ```python
         class MySSEWorkflow:
             async def on_stream_event(
                 self,
@@ -113,6 +116,7 @@ class StreamingResponseWorkflow(Protocol):
                 context: ExecutionContext,
             ) -> None:
                 await self._sse_channel.send_final(response.model_dump_json())
+        ```
     """
 
     async def on_stream_event(
@@ -162,7 +166,8 @@ class BaseDelegationResponseWorkflow:
             the ``result`` string. If *None*, the entire content dict is
             serialized as JSON. Defaults to *None*.
 
-    Example::
+    Example:
+        ```python
 
         async def publish(payload: dict) -> None:
             await my_transport.publish_reply(reply_to, correlation_id, payload)
@@ -171,6 +176,7 @@ class BaseDelegationResponseWorkflow:
             publish_fn=publish,
             output_field="report",
         )
+        ```
     """
 
     def __init__(

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/config/agent_settings.py

@@ -55,12 +55,13 @@ class BaseAgentSettings(AgentSettings):
     variables), so a ``{api_key}`` placeholder can never inline a secret. Read
     them at the point of use with ``.get_secret_value()``.
 
-    Example::
-
+    Example:
+        ```python
         class MySettings(BaseAgentSettings):
             CREDENTIAL_FIELDS = BaseAgentSettings.CREDENTIAL_FIELDS | {"search_api_key"}
 
             search_api_key: SecretStr = SecretStr("")
+        ```
     """
 
     # --- LLM gateway (canonical platform keys) ---

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/config/runtime_config.py

@@ -38,11 +38,13 @@ class AgentSettings(BaseModel):
     required and optional runtime configuration variables.
 
     Example:
+        ```python
         class MyAgentSettings(AgentSettings):
             reasoning_model: str              # required
             fast_model: str                   # required
             max_retries: int = 3              # optional with default
             temperature: float = 0.7          # optional with default
+        ```
     """
 
     model_config = ConfigDict(
@@ -85,6 +87,7 @@ class SettingsResolver(Generic[SettingsT]):
     graph execution without explicit parameter passing.
 
     Example:
+        ```python
         resolver = SettingsResolver(MyAgentSettings)
 
         # Resolve from incoming message
@@ -98,6 +101,7 @@ class SettingsResolver(Generic[SettingsT]):
 
         # Clear after execution
         resolver.clear()
+        ```
     """
 
     def __init__(self, settings_class: type[SettingsT]) -> None:

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/config/sdk_config.py

@@ -73,10 +73,12 @@ class SDKConfig(BaseModel):
     when setting up their agent. All values have sensible defaults.
 
     Example:
+        ```python
         config = SDKConfig(
             llm=LLMConfig(model="gpt-4o-mini"),
             strict_validation=True,
         )
+        ```
     """
 
     model_config = ConfigDict(frozen=True)

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/config/source.py

@@ -35,11 +35,13 @@ class ConfigSource(Protocol):
     return type.
 
     Example:
+        ```python
         class DatabaseConfigSource:
             async def fetch(
                 self, agent_name: str, conversation_id: str | None = None
             ) -> dict[str, Any]:
                 return await my_db.get_agent_config(agent_name)
+        ```
     """
 
     async def fetch(self, agent_name: str, conversation_id: str | None = None) -> dict[str, Any]:
@@ -66,8 +68,10 @@ class StaticConfigSource:
     fixed configuration applies to every agent and conversation.
 
     Example:
+        ```python
         source = StaticConfigSource({"model_name": "gpt-4o-mini", "api_key": "..."})
         config = await source.fetch("my_agent")
+        ```
     """
 
     def __init__(self, config: dict[str, Any]) -> None:
@@ -104,8 +108,10 @@ class EnvConfigSource:
         export SOFIAS_AGENT_CONFIG='{"model_name": "gpt-4o-mini", "api_key": "sk-..."}'
 
     Example:
+        ```python
         source = EnvConfigSource()  # reads SOFIAS_AGENT_CONFIG
         config = await source.fetch("my_agent")
+        ```
     """
 
     def __init__(self, env_var: str = "SOFIAS_AGENT_CONFIG") -> None:

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/contracts/agent_contracts.py

@@ -8,6 +8,7 @@ strongly-typed envelopes that carry domain data plus transport metadata.
 - AgentResponse wraps the validated output with execution metadata.
 
 Example:
+    ```python
     class MyInput(InputContract):
         query: str
 
@@ -22,6 +23,7 @@ Example:
     print(response.content)           # validated output dict
     print(response.execution_path)    # ["classifier", "responder"]
     print(response.execution_time_ms) # 1234.5
+    ```
 """
 
 from __future__ import annotations

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/contracts/base_contracts.py

@@ -6,6 +6,7 @@ a common protocol so that any delegating node knows exactly what to send and
 what to expect back, without needing to know the internals of the target agent.
 
 Example:
+    ```python
     # Agent A delegates to Agent B
     request = DelegationRequest(
         input="Summarize this document",
@@ -18,6 +19,7 @@ Example:
         result="The document discusses...",
         extras={"word_count": 150, "confidence": 0.95},
     )
+    ```
 """
 
 from __future__ import annotations

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/errors/error_handler.py

@@ -153,12 +153,14 @@ class ErrorHandler:
     callable provided by the agent.
 
     Example:
+        ```python
         handler = ErrorHandler(config=config, store=store)
         result = await handler.handle_node_execution(
             node_name="processor",
             execute_fn=node.execute,
             input_data={"query": "hello"},
         )
+        ```
     """
 
     def __init__(

sofias_sdk_lite-0.3.0/src/sofias_sdk_lite/mcp.py

@@ -0,0 +1,240 @@
+"""MCP connectors delivered by the Sofias platform.
+
+The platform sends each turn's connectors in ``AgentTaskMessage.mcp_servers``.
+Inside ``configuration`` it puts the transport details under ``__mcp_*`` keys:
+
+- ``__mcp_url``: the endpoint to call. For marketplace agents it is always the
+  platform's MCP intermediary, which adds the user's real credentials itself.
+- ``__mcp_headers``: headers for every request (a short-lived grant). Never put
+  them in a prompt or a log.
+- ``__mcp_tools``: the allow list approved for that connector.
+- ``__mcp_namespace``: offer the tools as ``connector__tool`` so two connectors
+  with a tool of the same name do not clash.
+
+``McpToolProvider`` implements the ``ToolProvider`` protocol on top of those
+entries with a minimal Streamable HTTP client (JSON-RPC over ``httpx``, JSON or
+event-stream answers, ``Mcp-Session-Id``), so it needs no extra dependency::
+
+    from sofias_sdk_lite.mcp import McpToolProvider
+    from sofias_sdk_lite.tools import ToolRegistry
+
+    provider = McpToolProvider(task.mcp_servers)
+    builder.with_tool_registry(ToolRegistry(provider))
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from sofias_sdk_lite.llm.tools import ToolSpec
+from sofias_sdk_lite.observability._log import get_logger
+
+logger = get_logger("mcp")
+
+__all__ = ["McpError", "McpServer", "McpToolProvider", "mcp_servers_from_message"]
+
+PROTOCOL_VERSION = "2025-06-18"
+_UNSUPPORTED = re.compile(r"[^A-Za-z0-9_-]")
+
+
+class McpError(Exception):
+    """An MCP server answered with an error or could not be reached."""
+
+
+@dataclass(frozen=True)
+class McpServer:
+    """One connector of the turn, ready to call."""
+
+    name: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    tools: tuple[str, ...] | None = None
+    namespace: bool = False
+
+
+def _field(raw: Any, name: str) -> Any:
+    return raw.get(name) if isinstance(raw, dict) else getattr(raw, name, None)
+
+
+def mcp_servers_from_message(raw_servers: list[Any]) -> list[McpServer]:
+    """Read the ``mcp_servers`` of a task message (models or plain dicts)."""
+    servers: list[McpServer] = []
+    for raw in raw_servers:
+        conf = dict(_field(raw, "conf") or _field(raw, "configuration") or {})
+        tools = conf.get("__mcp_tools")
+        servers.append(
+            McpServer(
+                name=str(_field(raw, "name")),
+                url=conf.get("__mcp_url") or f"http://{_field(raw, 'address')}:{_field(raw, 'port')}/mcp",
+                headers=dict(conf.get("__mcp_headers") or {}),
+                tools=tuple(tools) if tools else None,
+                namespace=bool(conf.get("__mcp_namespace") or conf.get("__mcp_headers")),
+            )
+        )
+    return servers
+
+
+def _offered_name(server: McpServer, tool: str) -> str:
+    if not server.namespace:
+        return tool
+    return _UNSUPPORTED.sub("_", f"{server.name}__{tool}")[:64]
+
+
+class _Session:
+    """A minimal Streamable HTTP MCP session against one server."""
+
+    def __init__(self, server: McpServer, client: httpx.AsyncClient) -> None:
+        self._server = server
+        self._client = client
+        self._session_id: str | None = None
+        self._next_id = 0
+        self._initialized = False
+
+    async def _post(self, payload: dict[str, Any]) -> dict[str, Any] | None:
+        headers = {
+            **self._server.headers,
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            "MCP-Protocol-Version": PROTOCOL_VERSION,
+        }
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+        try:
+            response = await self._client.post(self._server.url, json=payload, headers=headers)
+        except httpx.HTTPError as exc:
+            raise McpError(f"{self._server.name}: unreachable ({type(exc).__name__})") from exc
+        self._session_id = response.headers.get("Mcp-Session-Id") or self._session_id
+        if response.status_code == 202 or "id" not in payload:
+            return None
+        if response.status_code >= 400:
+            raise McpError(f"{self._server.name}: HTTP {response.status_code}")
+        message = self._message(response, payload["id"])
+        if message.get("error"):
+            raise McpError(f"{self._server.name}: {message['error'].get('message', message['error'])}")
+        return message.get("result") or {}
+
+    @staticmethod
+    def _message(response: httpx.Response, id_: int) -> dict[str, Any]:
+        if "text/event-stream" not in response.headers.get("Content-Type", ""):
+            return response.json()
+        messages = []
+        for event in re.split(r"\r?\n\r?\n", response.text):
+            data = "\n".join(line[5:].strip() for line in event.splitlines() if line.startswith("data:"))
+            if data:
+                try:
+                    messages.append(json.loads(data))
+                except json.JSONDecodeError:
+                    continue
+        for message in messages:
+            if message.get("id") == id_:
+                return message
+        raise McpError("event stream without an answer")
+
+    async def request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        if not self._initialized:
+            await self._initialize()
+        return await self._call(method, params) or {}
+
+    async def _call(self, method: str, params: dict[str, Any] | None) -> dict[str, Any] | None:
+        self._next_id += 1
+        payload: dict[str, Any] = {"jsonrpc": "2.0", "id": self._next_id, "method": method}
+        if params is not None:
+            payload["params"] = params
+        return await self._post(payload)
+
+    async def _initialize(self) -> None:
+        await self._call(
+            "initialize",
+            {"protocolVersion": PROTOCOL_VERSION, "capabilities": {},
+             "clientInfo": {"name": "sofias-sdk-lite", "version": "1"}},
+        )
+        await self._post({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        self._initialized = True
+
+
+class McpToolProvider:
+    """``ToolProvider`` over the connectors the platform sent for this turn.
+
+    Connects lazily on the first ``get_tools``. A connector that cannot be
+    reached is skipped (and logged) so the others keep working.
+    """
+
+    def __init__(self, raw_servers: list[Any], *, transport: httpx.AsyncBaseTransport | None = None,
+                 timeout: float = 60.0) -> None:
+        self._servers = mcp_servers_from_message(raw_servers)
+        self._client = httpx.AsyncClient(transport=transport, timeout=timeout)
+        self._sessions = {server.name: _Session(server, self._client) for server in self._servers}
+        self._routes: dict[str, tuple[str, str]] = {}
+        self._specs: list[ToolSpec] | None = None
+
+    async def get_tools(self, node_name: str) -> list[ToolSpec]:
+        if self._specs is None:
+            self._specs = []
+            for server in self._servers:
+                try:
+                    listed = await self._list(server)
+                except McpError as exc:
+                    logger.warning("mcp_server_unavailable", server=server.name, error=str(exc))
+                    continue
+                self._specs.extend(listed)
+        return list(self._specs)
+
+    async def _list(self, server: McpServer) -> list[ToolSpec]:
+        specs: list[ToolSpec] = []
+        cursor: str | None = None
+        while True:
+            result = await self._sessions[server.name].request("tools/list", {"cursor": cursor} if cursor else None)
+            for tool in result.get("tools", []):
+                name = tool.get("name")
+                if not name or (server.tools is not None and name not in server.tools):
+                    continue
+                offered = _offered_name(server, name)
+                self._routes[offered] = (server.name, name)
+                specs.append(ToolSpec(name=offered, description=tool.get("description") or name,
+                                      parameters_schema=tool.get("inputSchema") or {"type": "object"}))
+            cursor = result.get("nextCursor")
+            if not cursor:
+                return specs
+
+    async def execute_tool(self, tool_name: str, tool_input: dict[str, Any]) -> Any:
+        if self._specs is None:
+            await self.get_tools("")
+        route = self._routes.get(tool_name)
+        if route is None:
+            raise McpError(f"unknown MCP tool '{tool_name}'")
+        server_name, real_name = route
+        result = await self._sessions[server_name].request(
+            "tools/call", {"name": real_name, "arguments": tool_input or {}}
+        )
+        if result.get("isError"):
+            raise McpError(_text(result) or f"{tool_name} failed")
+        return _with_structured(result)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+def _text(result: dict[str, Any]) -> str:
+    return "\n".join(block.get("text", "") for block in result.get("content", []) if block.get("type") == "text")
+
+
+def _with_structured(result: dict[str, Any]) -> str:
+    """The text of a tool result plus its ``structuredContent``, unless the text
+    already is that same JSON. Some servers only put a summary in the text."""
+    text = _text(result)
+    structured = result.get("structuredContent")
+    if not structured:
+        return text if result.get("content") else json.dumps(result)
+    for block in result.get("content", []):
+        try:
+            if json.loads(block.get("text", "")) == structured:
+                return text
+        except (TypeError, ValueError):
+            continue
+    serialized = json.dumps(structured)
+    return f"{text}\n{serialized}" if text else serialized

{sofias_sdk_lite-0.2.0 → sofias_sdk_lite-0.3.0}/src/sofias_sdk_lite/messaging/models.py

@@ -332,6 +332,7 @@ class DelegationTarget(BaseModel):
     the communication with a specific target agent.
 
     Example:
+        ```python
         target = DelegationTarget(
             agent_name="summarizer",
             routing_key="agents.summarizer.tasks",
@@ -339,6 +340,7 @@ class DelegationTarget(BaseModel):
             output_contract=SummaryOutput,
             timeout_seconds=120,
         )
+        ```
 
     .. note::
         Unlike the internal platform, this SDK does **not** assume any
@@ -394,12 +396,14 @@ class DelegationStep(BaseModel):
     on other steps. Used when dynamic targets are enabled.
 
     Example:
+        ```python
         step = DelegationStep(
             id="step_1",
             agent_name="web-search",
             input={"query": "Bitcoin price"},
             depends_on=[],
         )
+        ```
     """
 
     model_config = {"frozen": True}
@@ -445,6 +449,7 @@ class DelegationPlan(BaseModel):
     delegation node running in DAG mode with dynamic targets.
 
     Example:
+        ```python
         plan = DelegationPlan(
             steps=[
                 DelegationStep(id="s1", agent_name="search", input={"q": "A"}),
@@ -452,6 +457,7 @@ class DelegationPlan(BaseModel):
                 DelegationStep(id="s3", agent_name="synthesizer", input={}, depends_on=["s1", "s2"]),
             ]
         )
+        ```
     """
 
     model_config = {"frozen": True}