pyagentic-core 2.10.1.dev2__tar.gz → 2.11.1.dev1__tar.gz

{pyagentic_core-2.10.1.dev2/pyagentic_core.egg-info → pyagentic_core-2.11.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.10.1.dev2
+Version: 2.11.1.dev1
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT

{pyagentic_core-2.10.1.dev2 → pyagentic_core-2.11.1.dev1}/docs/api/creating-an-app.md

@@ -59,6 +59,53 @@ app.include_router(create_router(MyAgent, model="openai::gpt-4o"), prefix="/bot"
 The router owns its `SessionManager`, exposed as `router.sessions` so you can
 share it (for example with `mount_mcp`).
 
+## Dependencies
+
+Agents often need resources that can't travel over HTTP — a database handle, an
+HTTP client, a pre-configured provider. Declare these with `Depends[...]` in the
+agent class, exactly where you'd otherwise put `State[...]`:
+
+```python
+from pyagentic import BaseAgent, State, Depends
+
+class ResearchAgent(BaseAgent):
+    __system_message__ = "You research topics."
+
+    topic: State[Topic]        # client-provided per session
+    db:    Depends[Database]    # injected server-side, never sent by clients
+```
+
+A `Depends[T]` field is **excluded** from the session/job request body. Instead
+you supply it once when building the app, via `dependencies=` — a list of
+instances or zero-arg factories, resolved **by type**:
+
+```python
+app = create_app(ResearchAgent, dependencies=[Database(dsn), make_client])
+```
+
+- An **instance** (`Database(dsn)`) is shared across every session.
+- A **factory** — a zero-arg callable annotated with its return type
+  (`def make_client() -> Client: ...`) — is called fresh for each agent built,
+  so every session and job gets its own.
+
+Each `Depends[T]` slot — including those declared on linked sub-agents — is
+matched to a provider of type `T`. Missing or mismatched dependencies fail fast
+when the app is built, not on the first request.
+
+For a multi-agent app, pass a flat list (applied to every agent) or a dict keyed
+by mount prefix to scope providers per agent:
+
+```python
+app = create_app(
+    {"/research": ResearchAgent, "/writer": WriterAgent},
+    dependencies={"/research": [Database(dsn)], "/writer": [make_client]},
+)
+```
+
+Linked agents are built from the request body — a session's body nests each
+`Link[...]` sub-agent's construction under its field name — while their
+`Depends[...]` fields are injected from the same `dependencies` list.
+
 ## Configuration: `agents.toml`
 
 Put an `agents.toml` next to your `pyproject.toml`. `create_app` reads its

{pyagentic_core-2.10.1.dev2 → pyagentic_core-2.11.1.dev1}/docs/api/index.md

@@ -53,14 +53,18 @@ field and the schemas update with no manual OpenAPI maintenance:
 
 | Route | Purpose |
 |---|---|
-| `GET /` | Agent metadata (name, tools, state fields, linked agents) |
+| `GET /` | Agent metadata (name, tools, state fields, linked agents, dependencies) |
 | `GET /health` | Liveness probe |
-| `GET /schema` | JSON schemas for request/response/stream-event/state |
-| `POST /sessions` | Create an isolated session |
+| `GET /schema` | JSON schemas for construct/request/response/stream-event/state |
+| `POST /sessions` | Create an isolated session (body mirrors the agent's constructor) |
 | `POST /sessions/{id}/chat` | Send a message, get a complete response |
 | `POST /sessions/{id}/chat/stream` | Stream typed SSE events as the agent works |
 | `GET /sessions/{id}/state` | Current agent state for a session |
 
+Creating a session constructs the agent: the body carries its state and any
+linked sub-agents (`POST /sessions`), while non-serializable resources are
+injected server-side with [`Depends[...]`](creating-an-app.md#dependencies).
+
 ## Guides
 
 <div class="grid cards" markdown>

{pyagentic_core-2.10.1.dev2 → pyagentic_core-2.11.1.dev1}/docs/api/jobs.md

@@ -58,7 +58,7 @@ result = httpx.get(f"http://localhost:8000/jobs/{job_id}").json()
 
 | Route | Purpose |
 |---|---|
-| `POST /jobs` | Submit a run. Body `{"input": {<chat fields>}, "session_id": <optional>}`. Returns `202 {job_id, status}`. |
+| `POST /jobs` | Submit a run. Body `{"input": {<chat fields>}, "session_id": <optional>, "construct": <optional>}`. Returns `202 {job_id, status}`. |
 | `GET /jobs` | List jobs, newest first. Filter with `?status=` and `?session_id=`. |
 | `GET /jobs/{id}` | Job status and, when terminal, its result. |
 | `GET /jobs/{id}/updates?since=<seq>` | The update log past a sequence cursor. |
@@ -69,6 +69,20 @@ The `input` object is your agent's normal chat request body. Pass a
 `session_id` (from `POST /sessions`) to run the job against an existing session;
 omit it for a one-off run.
 
+For a one-off run, add a `construct` object — the same construction data as
+`POST /sessions` (state and any nested linked agents) — to build a fresh agent
+for the job. Its [dependencies](creating-an-app.md#dependencies) are injected
+server-side, just like for sessions. Session-bound jobs reuse the session's
+existing agent and ignore `construct`.
+
+```python
+# One-off job that builds its own agent from a construct payload
+httpx.post("http://localhost:8000/jobs", json={
+    "input": {"user_input": "Summarize the latest results"},
+    "construct": {"topic": {"name": "kv-cache"}},
+})
+```
+
 ## Surviving timeouts: replay-from-cursor
 
 Every update carries a monotonic, gapless sequence number (`seq`), emitted on the

{pyagentic_core-2.10.1.dev2 → pyagentic_core-2.11.1.dev1}/docs/api/running.md

@@ -30,31 +30,49 @@ agent's prefix, e.g. `/research/sessions`.)
 ### Info routes
 
 ```bash
-# Agent metadata: name, version, tools, state fields, linked agents
+# Agent metadata: name, version, tools, state fields, linked agents, dependencies
 curl http://localhost:8000/
 
 # Liveness probe
 curl http://localhost:8000/health
 
-# JSON schemas for request, response, stream event, and state models
+# JSON schemas for construct, request, response, stream event, and state models
 curl http://localhost:8000/schema
 ```
 
+The `construct` schema describes the body for creating a session (or a
+sessionless job) — see below.
+
 ### Session management
 
 Sessions provide isolated agent instances with independent state and
 conversation history. Each session holds its own agent, so state changes in one
 session don't affect others.
 
+Creating a session **constructs the agent**, so the request body mirrors the
+constructor: the agent's `State[...]` fields, any `Link[...]` sub-agents
+(nested, recursively), and an optional `model`/`api_key`. Fields without a
+default are required; defaulted ones are optional. The exact shape is published
+at `GET /schema` under `construct`.
+
 ```bash
-# Create a new session (returns session_id)
+# Agent with no required construction fields — empty body is fine
 curl -X POST http://localhost:8000/sessions
 
-# Create with a model or API key override
+# Provide state and a per-session model
 curl -X POST http://localhost:8000/sessions \
   -H "Content-Type: application/json" \
-  -d '{"model": "openai::gpt-4o", "api_key": "sk-..."}'
+  -d '{"topic": {"name": "transformers"}, "model": "openai::gpt-4o"}'
 
+# A linked agent's construction nests under its field name
+curl -X POST http://localhost:8000/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"researcher": {"topic": {"name": "attention"}}}'
+```
+
+Omitting a required field returns `422`. List and delete are unchanged:
+
+```bash
 # List all active session IDs
 curl http://localhost:8000/sessions
 
@@ -64,6 +82,11 @@ curl -X DELETE http://localhost:8000/sessions/{session_id}
 
 Sessions are stored in memory — restarting the server clears them.
 
+!!! note "Dependencies aren't part of the body"
+    `Depends[...]` fields (database handles, clients, providers) are injected
+    server-side when the app is built, never sent by clients — see
+    [Dependencies](creating-an-app.md#dependencies).
+
 ### Chat
 
 The chat request body is automatically derived from your agent's `__call__`
@@ -125,14 +148,17 @@ Returns the full state model, serialized using the agent's `__state_class__`.
 `create_app` extracts the agent's metaclass-generated models and wires them to
 the routes:
 
+- `__construct_model__` → session create body (state + nested linked agents)
 - `__request_model__` → chat request body
 - `__response_model__` → chat response body
 - `__stream_event_model__` → typed SSE events
 - `__state_class__` → state endpoint
 
 A `SessionManager` (an in-memory store holding one agent instance per session)
-backs the session routes. The streaming endpoint drives `agent.step()`; the
-synchronous endpoint calls `agent(**kwargs)`.
+backs the session routes. Creating a session builds a fresh agent from the
+construct body plus any server-injected [dependencies](creating-an-app.md#dependencies).
+The streaming endpoint drives `agent.step()`; the synchronous endpoint calls
+`agent(**kwargs)`.
 
 ## Next steps
 

{pyagentic_core-2.10.1.dev2 → pyagentic_core-2.11.1.dev1}/pyagentic/__init__.py

@@ -30,6 +30,7 @@ Main Components:
     - tool: Decorator for marking methods as LLM-callable tools
     - State: Type annotation for persistent state fields
     - Link: Type annotation for linking agents together
+    - Depends: Type annotation for dependency-injected agent fields
     - spec: Configuration factory for state, params, and agent links
     - ref: Dynamic state reference system for tool parameters
     - AgentExtension: Base class for creating reusable agent mixins
@@ -42,6 +43,17 @@ from pyagentic._base._mcp import MCPLink
 from pyagentic._base._tool import tool
 
 from pyagentic._base._state import State
+from pyagentic._base._depends import Depends
 from pyagentic._base._ref import ref
 
-__all__ = ["BaseAgent", "AgentExtension", "tool", "spec", "State", "Link", "MCPLink", "ref"]
+__all__ = [
+    "BaseAgent",
+    "AgentExtension",
+    "tool",
+    "spec",
+    "State",
+    "Link",
+    "Depends",
+    "MCPLink",
+    "ref",
+]

{pyagentic_core-2.10.1.dev2 → pyagentic_core-2.11.1.dev1}/pyagentic/_base/_agent/_agent.py

@@ -163,6 +163,7 @@ class BaseAgent(metaclass=AgentMeta):
     __state_defs__: ClassVar[dict[str, _StateDefinition]]  # State field definitions
     __linked_agents__: ClassVar[dict[str, "_LinkedAgentDefinition"]]  # Linked agent definitions
     __mcp_defs__: ClassVar[dict[str, "_MCPDefinition"]]  # MCP server definitions
+    __dependencies__: ClassVar[dict[str, type]]  # Depends[T] field -> dependency type
 
     # User-set Class Attributes (defined in subclass)
     __system_message__: ClassVar[str]  # Required: system prompt for the agent
@@ -173,6 +174,7 @@ class BaseAgent(metaclass=AgentMeta):
 
     # Generated Class Attributes (built by metaclass)
     __request_model__: ClassVar[Type[BaseModel]] = None  # Pydantic request model from __call__
+    __construct_model__: ClassVar[Type[BaseModel]] = None  # Recursive constructor model
     __response_model__: ClassVar[Type[AgentResponse]] = None  # Pydantic response model
     __stream_event_model__: ClassVar[Type[BaseModel]] = None  # Typed SSE stream event union
     __state_class__: ClassVar[Type[_AgentState]] = None  # Generated state class

pyagentic_core-2.11.1.dev1/pyagentic/_base/_depends.py

@@ -0,0 +1,59 @@
+from typing import TypeVar, Generic
+
+T = TypeVar("T")
+
+
+class Depends(Generic[T]):
+    """
+    Type annotation for declaring a dependency-injected agent field.
+
+    ``Depends`` marks a field as a server-supplied dependency rather than
+    serializable per-session state. Use it in an agent's class body wherever you
+    would otherwise use :class:`State`, for resources that cannot (or should not)
+    travel over the wire — database handles, HTTP clients, pre-configured
+    providers, and similar.
+
+    Unlike ``State`` and ``Link``, a ``Depends`` field is **excluded** from the
+    agent's generated construct model: clients never provide it. Instead it is
+    supplied once by the developer at :func:`pyagentic.api.create_router` /
+    :func:`pyagentic.api.create_app` via the ``dependencies`` argument, and
+    resolved by type across the (possibly nested) agent tree.
+
+    Args:
+        T: The dependency type. Used both as the field's type hint and as the key
+            for by-type resolution at serve time.
+
+    Example:
+        ```python
+        from pyagentic import BaseAgent, State, Depends
+
+        class ResearchAgent(BaseAgent):
+            __system_message__ = "You research topics"
+
+            topic: State[TopicState]      # client-provided per session
+            db:    Depends[Database]      # injected by the developer, by type
+
+            @tool("Look up a record")
+            def lookup(self, key: str) -> str:
+                return self.db.get(key)
+        ```
+    """
+
+    def __class_getitem__(cls, item):
+        """
+        Creates a generic Depends type marker for a given dependency class.
+
+        Args:
+            item: The dependency class this field requires.
+
+        Returns:
+            type: Special marker type that the metaclass detects and records in
+                ``__dependencies__`` (and excludes from the construct model).
+        """
+        # Return a special marker type that the metaclass can detect, mirroring
+        # the State[T] / Link[T] markers.
+        return type(
+            f"Depends[{item.__name__}]",
+            (),
+            {"__origin__": Depends, "__args__": (item,), "__dependency_type__": item},
+        )

{pyagentic_core-2.10.1.dev2 → pyagentic_core-2.11.1.dev1}/pyagentic/_base/_metaclasses.py

@@ -15,6 +15,7 @@ from pyagentic._base._agent._agent_state import _AgentState
 from pyagentic._base._tool import _ToolDefinition, tool
 from pyagentic._base._state import State, StateInfo, _StateDefinition
 from pyagentic._base._agent._agent_linking import Link, _LinkedAgentDefinition
+from pyagentic._base._depends import Depends
 from pyagentic._base._mcp import MCPLink, _MCPDefinition
 
 from pyagentic.models.response import AgentResponse, ToolResponse
@@ -323,6 +324,92 @@ class AgentMeta(type):
 
         return MappingProxyType(mcp_defs)
 
+    @staticmethod
+    def _extract_dependencies(annotations, namespace) -> Mapping[str, type]:
+        """Extracts dependency-injected fields declared with ``Depends[T]``.
+
+        Looks for annotations whose marker has ``__origin__ is Depends`` and
+        records the wrapped dependency type. These fields are injected at serve
+        time (by type) rather than supplied by clients, so they are excluded from
+        the generated construct model.
+
+        Args:
+            annotations (dict): Combined annotations from the class hierarchy.
+            namespace (dict): The class namespace.
+
+        Returns:
+            Mapping[str, type]: Immutable mapping of field name to dependency type.
+        """
+        dependencies: dict[str, type] = {}
+
+        for attr_name, attr_type in annotations.items():
+            if getattr(attr_type, "__origin__", None) is Depends:
+                dependencies[attr_name] = attr_type.__dependency_type__
+
+        return MappingProxyType(dependencies)
+
+    @staticmethod
+    def _build_construct_model(cls) -> Type[BaseModel]:
+        """Build a recursive Pydantic model mirroring the agent's constructor.
+
+        The construct model is the serializable construction contract for the
+        agent: it carries the data a client must supply to instantiate one, in a
+        way that mirrors writing the construction in Python.
+
+          - State fields → the raw per-field model, required when the StateInfo
+            has no default/default_factory, otherwise optional.
+          - Linked agents → that agent's own ``__construct_model__`` (nested),
+            optional when the AgentLink provides a default, otherwise required.
+          - ``model`` / ``api_key`` → optional scalars for provider selection.
+
+        ``Depends`` and MCP fields are excluded — they are injected/configured
+        server-side, not provided by clients.
+
+        Args:
+            cls: The agent class whose constructor to mirror.
+
+        Returns:
+            Type[BaseModel]: A dynamically created Pydantic model.
+        """
+        from typing import Optional
+        from pydantic import ConfigDict
+
+        fields: dict[str, Any] = {}
+
+        # State fields: type is the raw per-field model (e.g. UserProfile).
+        # Check for a default's *existence* without invoking factories.
+        for name, state_def in cls.__state_defs__.items():
+            info = state_def.info
+            if info.default_factory is not None:
+                fields[name] = (state_def.model, Field(default_factory=info.default_factory))
+            elif info.default is not None:
+                fields[name] = (state_def.model, Field(default=info.default))
+            else:
+                fields[name] = (state_def.model, Field(...))
+
+        # Linked agents: nest each child's construct model. A link is optional
+        # when its AgentLink declares any default (don't call the factory here).
+        for name, linked_def in cls.__linked_agents__.items():
+            child_model = linked_def.agent.__construct_model__
+            info = linked_def.info
+            has_default = info is not None and (
+                info.default is not None or info.default_factory is not None
+            )
+            if has_default:
+                fields[name] = (Optional[child_model], Field(default=None))
+            else:
+                fields[name] = (child_model, Field(...))
+
+        # Provider selection scalars.
+        fields["model"] = (Optional[str], Field(default=None))
+        fields["api_key"] = (Optional[str], Field(default=None))
+
+        return create_model(
+            f"{cls.__name__}Construct",
+            __config__=ConfigDict(arbitrary_types_allowed=True),
+            **fields,
+        )
+
     @staticmethod
     def _build_request_model(cls) -> Type[BaseModel]:
         """Build a Pydantic request model from the agent's __call__ signature.
@@ -458,6 +545,16 @@ class AgentMeta(type):
             # MCP fields are config-only, not constructor args
             elif field_name in agent_cls.__mcp_defs__:
                 continue
+            # Dependency-injected fields are optional (default None); they are
+            # supplied at serve time or passed explicitly for direct/test use.
+            elif field_name in agent_cls.__dependencies__:
+                param = inspect.Parameter(
+                    field_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    default=None,
+                    annotation=field_type,
+                )
+                optional.append(param)
             # Other annotated fields (like model, api_key, tracer, etc.)
             else:
                 default = getattr(agent_cls, field_name, inspect._empty)
@@ -611,12 +708,14 @@ class AgentMeta(type):
             annotations, inherited_namespace | namespace, mcs.__BaseAgent__
         )
         mcp_defs = mcs._extract_mcp_defs(annotations, inherited_namespace | namespace)
+        dependencies = mcs._extract_dependencies(annotations, inherited_namespace | namespace)
         with mcs._lock:
             cls.__tool_defs__ = tool_defs
             cls.__annotations__ = annotations
             cls.__state_defs__ = state_defs
             cls.__linked_agents__ = linked_agents
             cls.__mcp_defs__ = mcp_defs
+            cls.__dependencies__ = dependencies
 
         # Create response models at class declaration time, giving the agent a predetermined
         # output structure. This allows developers to know exactly what the output of the
@@ -668,10 +767,16 @@ class AgentMeta(type):
             ResponseModel=ResponseModel,
         )
 
+        # Build the recursive construct model mirroring the agent's constructor.
+        # Linked agents' construct models already exist because their classes are
+        # defined before this one (same guarantee relied on for __response_model__).
+        ConstructModel = mcs._build_construct_model(cls)
+
         with mcs._lock:
             cls.__tool_response_models__ = MappingProxyType(tool_response_models)
             cls.__response_model__ = ResponseModel
             cls.__request_model__ = RequestModel
+            cls.__construct_model__ = ConstructModel
             cls.__stream_event_model__ = StreamEventModel
             cls.__state_class__ = StateClass
 

{pyagentic_core-2.10.1.dev2 → pyagentic_core-2.11.1.dev1}/pyagentic/api/__init__.py

@@ -11,7 +11,9 @@ Configuration lives in ``agents.toml`` beside your ``pyproject.toml`` (see
 :class:`AgentsConfig`).
 """
 
+from pyagentic._base._depends import Depends
 from pyagentic.api._app import create_app, create_router
+from pyagentic.api._build import build_agent, validate_dependencies
 from pyagentic.api._config import (
     AgentsConfig,
     AppConfig,
@@ -25,7 +27,6 @@ from pyagentic.api._models import (
     AgentInfo,
     AppAgentEntry,
     AppIndex,
-    CreateSessionRequest,
     CreateSessionResponse,
     DeleteSessionResponse,
     HealthResponse,
@@ -38,6 +39,9 @@ __all__ = [
     "create_app",
     "create_router",
     "mount_mcp",
+    "Depends",
+    "build_agent",
+    "validate_dependencies",
     "generate_dockerfile",
     "write_dockerfile",
     "AgentsConfig",
@@ -50,7 +54,6 @@ __all__ = [
     "AgentInfo",
     "AppAgentEntry",
     "AppIndex",
-    "CreateSessionRequest",
     "CreateSessionResponse",
     "DeleteSessionResponse",
     "HealthResponse",