pyagentic-core 2.6.2rc1__tar.gz → 2.7.0a2__tar.gz

{pyagentic_core-2.6.2rc1/pyagentic_core.egg-info → pyagentic_core-2.7.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.6.2rc1
+Version: 2.7.0a2
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT
@@ -26,13 +26,9 @@ Requires-Dist: jinja2>=3.1.6
 Requires-Dist: fastmcp>=3.4.0
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=2.0.0; extra == "mcp"
-Provides-Extra: deploy
-Requires-Dist: typer>=0.15.0; extra == "deploy"
-Requires-Dist: fastapi>=0.115.0; extra == "deploy"
-Requires-Dist: uvicorn>=0.34.0; extra == "deploy"
-Requires-Dist: sse-starlette>=2.0.0; extra == "deploy"
-Requires-Dist: httpx>=0.28.0; extra == "deploy"
-Requires-Dist: fastmcp>=2.0.0; extra == "deploy"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115.0; extra == "api"
+Requires-Dist: uvicorn>=0.34.0; extra == "api"
 Dynamic: license-file
 
 # PyAgentic

pyagentic_core-2.7.0a2/docs/api/creating-an-app.md

@@ -0,0 +1,108 @@
+# Creating an App
+
+`create_app` builds a standalone FastAPI application from one or more agents.
+`create_router` builds an `APIRouter` you can mount into an app you already
+have. Both derive their routes from the agent's metaclass-generated models.
+
+## A single agent
+
+Pass the class; it's served at the root:
+
+```python
+from pyagentic.api import create_app
+
+app = create_app(MyAgent, model="openai::gpt-4o")
+```
+
+`model` is the default LLM used for sessions that don't override it. `name`,
+`version`, and `description` set the FastAPI metadata (and default from
+`agents.toml`, see below).
+
+## Multiple agents
+
+Pass a list and each agent is mounted under a prefix derived from its class name
+(`ResearchAgent` → `/research`, `WriterAgent` → `/writer`). A top-level
+`GET /` index lists what's mounted, and `GET /health` is added:
+
+```python
+app = create_app([ResearchAgent, WriterAgent])
+# /research/sessions, /research/chat, ...
+# /writer/sessions,   /writer/chat,   ...
+```
+
+For explicit prefixes, pass a `{prefix: agent}` mapping:
+
+```python
+app = create_app({"/research": ResearchAgent, "/writer": WriterAgent})
+```
+
+Each agent gets its own isolated `SessionManager` — sessions, state, and (if
+enabled) jobs never cross between agents.
+
+!!! note "Linked agents stay subordinate"
+    Agents connected with `Link[...]` are called through their parent agent's
+    tools, not exposed as separate endpoints. "Multiple agents" here means
+    several independent top-level agents on one app.
+
+## Mounting into an existing app
+
+Use `create_router` to add an agent to a FastAPI app you already run:
+
+```python
+from fastapi import FastAPI
+from pyagentic.api import create_router
+
+app = FastAPI()
+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`).
+
+## Configuration: `agents.toml`
+
+Put an `agents.toml` next to your `pyproject.toml`. `create_app` reads its
+`[app]` section for defaults; explicit keyword arguments override it.
+
+```toml
+[app]
+name = "my-agents"
+version = "0.1.0"
+description = "My agent service"
+model = "openai::gpt-4o"   # default model for sessions
+```
+
+```python
+app = create_app(MyAgent)          # name/version/model come from agents.toml
+app = create_app(MyAgent, model="anthropic::claude-sonnet-4-6")  # override
+```
+
+`agents.toml` also has `[deploy]` (see [Deploying](deploying.md)) and `[jobs]`
+(see [Async Jobs](jobs.md)) sections.
+
+## Exposing the agent over MCP
+
+Pass `mcp=True` to also mount a [Model Context Protocol](https://modelcontextprotocol.io)
+endpoint per agent at `<prefix>/mcp`, sharing the same sessions as the HTTP routes:
+
+```python
+app = create_app(MyAgent, mcp=True)   # MCP server at /mcp
+```
+
+To mount MCP onto your own app, use `mount_mcp`:
+
+```python
+from pyagentic.api import create_router, mount_mcp
+
+router = create_router(MyAgent)
+app.include_router(router, prefix="/bot")
+mount_mcp(app, MyAgent, sessions=router.sessions, path="/bot/mcp")
+```
+
+`mount_mcp` requires the `fastmcp` extra (`pip install pyagentic-core[mcp]`).
+
+## Next steps
+
+- [Run your app](running.md) and explore the HTTP API
+- Enable [durable async jobs](jobs.md) for long-running calls
+- [Deploy](deploying.md) it as a container

pyagentic_core-2.7.0a2/docs/api/deploying.md

@@ -0,0 +1,80 @@
+# Deploying
+
+Your app is a standard ASGI application, so it deploys like any FastAPI service:
+run `uvicorn main:app` in a container. PyAgentic can generate a Dockerfile for
+you from `agents.toml`.
+
+## The `[deploy]` section
+
+Add a `[deploy]` section to `agents.toml` (beside your `pyproject.toml`):
+
+```toml
+[deploy]
+target = "main:app"        # the ASGI app uvicorn serves
+python_version = "3.13"
+dependencies = []          # extra pip packages to install in the image
+port = 8000
+env = ["OPENAI_API_KEY"]   # environment variables required at runtime
+```
+
+## Generating a Dockerfile
+
+```python
+from pyagentic.api import write_dockerfile
+
+write_dockerfile()   # reads ./agents.toml, writes ./Dockerfile
+```
+
+Or get the contents as a string with `generate_dockerfile()`. The generated
+Dockerfile installs your project and runs it with uvicorn:
+
+```dockerfile
+FROM python:3.13-slim
+WORKDIR /app
+RUN pip install uv
+
+RUN uv pip install --system "pyagentic-core[api]"
+
+COPY . .
+EXPOSE 8000
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+Extra `[deploy].dependencies` are installed as an additional step:
+
+```toml
+[deploy]
+dependencies = ["pandas", "numpy"]
+```
+
+```dockerfile
+# Added automatically:
+RUN uv pip install --system "pandas" "numpy"
+```
+
+## Building and running
+
+Build and run with your normal Docker tooling:
+
+```bash
+docker build -t my-agents:0.1.0 .
+docker run -p 8000:8000 --env-file .env my-agents:0.1.0
+```
+
+Pass secrets via `--env-file` or `-e` (the variables you listed in
+`[deploy].env`):
+
+```bash
+docker run -p 8000:8000 -e OPENAI_API_KEY=sk-... my-agents:0.1.0
+```
+
+!!! tip "Durable jobs in a container"
+    If you use [async jobs](jobs.md), set `[jobs].store` to a path on a mounted
+    volume so job records survive container restarts. The default
+    `.pyagentic/jobs.db` lives in the container's filesystem and is lost when the
+    container is removed.
+
+## Next steps
+
+- Review [async jobs](jobs.md) for long-running deployments
+- Explore [observability](../observability.md) to trace agents in production

pyagentic_core-2.7.0a2/docs/api/index.md

@@ -0,0 +1,103 @@
+# API
+
+PyAgentic turns an agent class into a FastAPI application (or a router you mount
+into your own app), with an HTTP API generated automatically from the agent's
+tools, state, and input signature. Optionally expose it over MCP, run long calls
+as durable background jobs, and generate a Dockerfile to ship it.
+
+## Installation
+
+The serving tools ship as an optional extra:
+
+```bash
+pip install pyagentic-core[api]
+```
+
+This installs FastAPI and uvicorn alongside the core package.
+
+## Quickstart
+
+Write a `main.py` that builds the app from your agent class:
+
+```python
+# main.py
+from pyagentic import BaseAgent, tool
+from pyagentic.api import create_app
+
+
+class AssistantAgent(BaseAgent):
+    __system_message__ = "You are a helpful assistant."
+
+    @tool("Add two numbers")
+    def add(self, a: int, b: int) -> str:
+        return str(a + b)
+
+
+app = create_app(AssistantAgent, model="openai::gpt-4o")
+```
+
+Run it with uvicorn:
+
+```bash
+uvicorn main:app --reload
+```
+
+That's the whole loop — no CLI, no scaffolding. Your agent is now served at
+`http://localhost:8000` with session management, chat, streaming, and a schema
+endpoint, all derived from the class.
+
+## What you get
+
+The generated API always reflects your agent — add a tool parameter or state
+field and the schemas update with no manual OpenAPI maintenance:
+
+| Route | Purpose |
+|---|---|
+| `GET /` | Agent metadata (name, tools, state fields, linked agents) |
+| `GET /health` | Liveness probe |
+| `GET /schema` | JSON schemas for request/response/stream-event/state |
+| `POST /sessions` | Create an isolated session |
+| `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 |
+
+## Guides
+
+<div class="grid cards" markdown>
+
+- :material-application-cog: **[Creating an App](creating-an-app.md)**
+
+    ---
+
+    Build an app or router from one or many agents, configure it with
+    `agents.toml`, and mount it into an existing FastAPI app.
+
+    [:octicons-arrow-right-24: Build it](creating-an-app.md)
+
+- :material-play-circle: **[Running](running.md)**
+
+    ---
+
+    Run with uvicorn and explore the auto-generated HTTP API: sessions, chat,
+    streaming, and state.
+
+    [:octicons-arrow-right-24: Run locally](running.md)
+
+- :material-clock-fast: **[Async Jobs](jobs.md)**
+
+    ---
+
+    Run agents that take longer than an HTTP request: submit a durable job and
+    stream its updates, surviving timeouts and reconnects.
+
+    [:octicons-arrow-right-24: Go async](jobs.md)
+
+- :material-docker: **[Deploying](deploying.md)**
+
+    ---
+
+    Generate a Dockerfile from `agents.toml` and ship your agent as a container.
+
+    [:octicons-arrow-right-24: Ship it](deploying.md)
+
+</div>

pyagentic_core-2.7.0a2/docs/api/jobs.md

@@ -0,0 +1,115 @@
+# Async Jobs
+
+A `/chat` request runs the agent inside the HTTP request and returns when it's
+done. That's fine for quick calls, but an agent that researches, calls tools,
+and chains for several minutes will outlast client read timeouts, load-balancer
+idle limits, and flaky connections.
+
+The job system solves this. You **submit** an agent run, it executes in the
+background as a **durable record**, and you **stream or poll** its updates
+later — surviving timeouts, disconnects, and reconnects.
+
+## Enabling jobs
+
+Jobs are opt-in. Turn them on in code:
+
+```python
+from pyagentic.api import create_app
+
+app = create_app(MyAgent, model="openai::gpt-4o", jobs=True)
+```
+
+or in `agents.toml`:
+
+```toml
+[jobs]
+enabled = true
+store = ".pyagentic/jobs.db"   # SQLite path; ":memory:" for ephemeral
+admission_cap = 16             # max jobs in-flight at once
+max_concurrency = 8            # max concurrent agent runs
+ttl = "24h"                    # how long terminal job records are kept
+cleanup_interval_seconds = 300
+```
+
+This mounts a `/jobs` API per agent (under each agent's prefix in a multi-agent
+app) and persists job records and their update logs to SQLite, so they survive a
+server restart.
+
+## The flow
+
+```python
+import httpx
+
+# 1. Submit — returns immediately with a job id (202)
+r = httpx.post("http://localhost:8000/jobs",
+               json={"input": {"user_input": "Research AI safety"}})
+job_id = r.json()["job_id"]
+
+# 2. Stream updates as the agent works (resumable — see below)
+with httpx.stream("GET", f"http://localhost:8000/jobs/{job_id}/stream") as s:
+    for line in s.iter_lines():
+        print(line)
+
+# 3. Or just fetch the final result when you're ready
+result = httpx.get(f"http://localhost:8000/jobs/{job_id}").json()
+```
+
+## Endpoints
+
+| Route | Purpose |
+|---|---|
+| `POST /jobs` | Submit a run. Body `{"input": {<chat fields>}, "session_id": <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. |
+| `GET /jobs/{id}/stream` | SSE stream of updates: replay from cursor, then live tail. |
+| `POST /jobs/{id}/cancel` | Cancel a queued or running job. |
+
+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.
+
+## Surviving timeouts: replay-from-cursor
+
+Every update carries a monotonic, gapless sequence number (`seq`), emitted on the
+SSE stream as the frame `id`. If the connection drops, reconnect with the
+`Last-Event-ID` header (or `?since=<seq>`) and the stream replays **only** what
+you missed, then resumes the live tail:
+
+```
+event: llm_response
+id: 0
+data: {...}
+
+event: tool_response
+id: 1
+data: {...}
+```
+
+```bash
+# Reconnect after seq 1 — replays seq 2 onward, then tails live
+curl -N http://localhost:8000/jobs/{id}/stream \
+  -H "Last-Event-ID: 1"
+```
+
+The stream closes after a terminal event (`agent_response`, `job_failed`, or
+`job_cancelled`). Because the store is the single source of truth, a client can
+disconnect for any reason and pick up exactly where it left off — the agent run
+keeps going server-side regardless.
+
+## How it works
+
+- **Durable store** — a `JobStore` (SQLite by default) holds each job record and
+  its append-only update log. Restarting the server keeps finished jobs and
+  their logs; an in-flight `running` job is marked failed on restart (execution
+  is not resumed), and `queued` jobs are re-dispatched.
+- **In-process backend** — runs `agent.step()` in the server's event loop and
+  emits each update. Session-bound jobs run on the session's live agent;
+  the orchestrator serializes a session's jobs FIFO (one in-flight per session).
+- **Admission cap** — a single process-wide cap bounds concurrent runs; jobs
+  beyond it stay `queued` until a slot frees.
+
+## Next steps
+
+- [Deploy](deploying.md) your app — set a persistent `[jobs].store` path in the container
+- Revisit the [synchronous chat endpoints](running.md#chat) for quick calls

pyagentic_core-2.7.0a2/docs/api/running.md

@@ -0,0 +1,141 @@
+# Running
+
+Your app is an ordinary ASGI application, so you run it with uvicorn (or any
+ASGI server). The API is generated from your agent's class — tools, state, and
+input signature all become typed endpoints with zero configuration.
+
+## Run with uvicorn
+
+```bash
+uvicorn main:app --reload
+```
+
+`main:app` points at the `app = create_app(...)` in your `main.py`. Use
+`--reload` for auto-restart during development, and `--host`/`--port` to change
+the bind address:
+
+```bash
+uvicorn main:app --host 0.0.0.0 --port 3000
+```
+
+The interactive OpenAPI docs are available at `http://localhost:8000/docs`.
+
+## API endpoints
+
+All request and response schemas are derived from your agent's
+metaclass-generated models — adding a tool parameter or state field
+automatically updates the API. (For a multi-agent app, these live under each
+agent's prefix, e.g. `/research/sessions`.)
+
+### Info routes
+
+```bash
+# Agent metadata: name, version, tools, state fields, linked agents
+curl http://localhost:8000/
+
+# Liveness probe
+curl http://localhost:8000/health
+
+# JSON schemas for request, response, stream event, and state models
+curl http://localhost:8000/schema
+```
+
+### 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.
+
+```bash
+# Create a new session (returns session_id)
+curl -X POST http://localhost:8000/sessions
+
+# Create with a model or API key override
+curl -X POST http://localhost:8000/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"model": "openai::gpt-4o", "api_key": "sk-..."}'
+
+# List all active session IDs
+curl http://localhost:8000/sessions
+
+# Delete a session
+curl -X DELETE http://localhost:8000/sessions/{session_id}
+```
+
+Sessions are stored in memory — restarting the server clears them.
+
+### Chat
+
+The chat request body is automatically derived from your agent's `__call__`
+signature. With the default signature, the body is `{"user_input": "..."}`; if
+you override `__call__` with custom parameters, the schema updates to match.
+
+```bash
+curl -X POST http://localhost:8000/sessions/{session_id}/chat \
+  -H "Content-Type: application/json" \
+  -d '{"user_input": "Hello!"}'
+```
+
+### Streaming
+
+The stream endpoint returns [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
+with typed events as the agent works:
+
+```bash
+curl -N -X POST http://localhost:8000/sessions/{session_id}/chat/stream \
+  -H "Content-Type: application/json" \
+  -d '{"user_input": "Research AI safety"}'
+```
+
+```
+event: llm_response
+data: {"event": "llm_response", "data": {...}}
+
+event: tool_response
+data: {"event": "tool_response", "data": {...}}
+
+event: agent_response
+data: {"event": "agent_response", "data": {...}}
+```
+
+- `llm_response` — Fired after each LLM inference. The model's text and any tool calls.
+- `tool_response` — Fired after each tool execution. The tool name, arguments, and result.
+- `agent_response` — Fired once at the end with the complete `AgentResponse`.
+
+This maps directly to the three response types from
+[`agent.step()`](../execution-modes.md): `LLMResponse`, `ToolResponse`, and
+`AgentResponse`.
+
+!!! tip "Long-running agents"
+    `/chat` and `/chat/stream` run within the HTTP request — fine for quick
+    calls, but a multi-minute agent run can outlive client or proxy timeouts.
+    For those, submit a [durable job](jobs.md) instead and stream its updates.
+
+### State
+
+```bash
+# Get the current agent state for a session
+curl http://localhost:8000/sessions/{session_id}/state
+```
+
+Returns the full state model, serialized using the agent's `__state_class__`.
+
+## How it works
+
+`create_app` extracts the agent's metaclass-generated models and wires them to
+the routes:
+
+- `__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)`.
+
+## Next steps
+
+- Add [durable async jobs](jobs.md) for long-running calls
+- [Deploy](deploying.md) your app as a Docker image
+- Review the [architecture reference](../reference/architecture.md) for runtime internals

{pyagentic_core-2.6.2rc1 → pyagentic_core-2.7.0a2}/docs/index.md

@@ -104,13 +104,13 @@ Dive deeper into PyAgentic's powerful features:
 
     [:octicons-arrow-right-24: Trace behavior](observability.md)
 
-- :material-rocket-launch: **[Deploy](deploy/index.md)**
+- :material-rocket-launch: **[API](api/index.md)**
 
     ---
 
-    Scaffold, run, build, and publish agents with the PyAgentic CLI.
+    Turn agents into a FastAPI app or router, run async jobs, and ship a Docker image.
 
-    [:octicons-arrow-right-24: Deploy your agent](deploy/index.md)
+    [:octicons-arrow-right-24: Serve your agent](api/index.md)
 
 </div>
 

{pyagentic_core-2.6.2rc1 → pyagentic_core-2.7.0a2}/mkdocs.yml

@@ -18,12 +18,13 @@ nav:
     - MCP: mcp.md
     - Inheritance: inheritance.md
     - Observability: observability.md
-  - Deploy:
-    - Overview: deploy/index.md
-    - Create a Project: deploy/creating-a-project.md
-    - Run Your Project: deploy/running.md
-    - Build & Deploy: deploy/building.md
-  - API Reference:
+  - API:
+    - Overview: api/index.md
+    - Creating an App: api/creating-an-app.md
+    - Running: api/running.md
+    - Async Jobs: api/jobs.md
+    - Deploying: api/deploying.md
+  - Code Reference:
       - Architecture: reference/architecture.md
       - Modules: reference/modules.md
 

{pyagentic_core-2.6.2rc1 → pyagentic_core-2.7.0a2}/pyagentic/_base/_agent/_agent.py

@@ -278,7 +278,9 @@ class BaseAgent(metaclass=AgentMeta):
         mcp_response_models = {}
 
         for field_name, mcp_def in self.__mcp_defs__.items():
-            info = mcp_def.info
+            # Resolve StateRefs (e.g. ref.self.root in server/args) the same
+            # way _get_tool_defs resolves them in tool definitions.
+            info = mcp_def.info.resolve(self.agent_reference)
             server = info.server
 
             # Auto-detect transport

{pyagentic_core-2.6.2rc1 → pyagentic_core-2.7.0a2}/pyagentic/_base/_info.py

@@ -22,17 +22,19 @@ class _SpecInfo:
             return None
 
     def resolve(self, agent_reference: dict) -> Self:
+        def _resolve_value(value: Any) -> Any:
+            if isinstance(value, RefNode):
+                return value.resolve(agent_reference)
+            if isinstance(value, list):
+                # resolve refs nested in list fields, e.g. MCPInfo.args
+                return [_resolve_value(item) for item in value]
+            return value
+
         attrs: dict[str, Any] = {}
 
         # walk actual model fields, not the dumped / serialized version
-        for name, value in self.__dict__.items():
-            value = getattr(self, name)
-
-            if isinstance(value, RefNode):
-                resolved = value.resolve(agent_reference)
-                attrs[name] = resolved
-            else:
-                attrs[name] = value
+        for name in self.__dict__:
+            attrs[name] = _resolve_value(getattr(self, name))
 
         # rebuild same class with resolved attrs
         return self.__class__(**attrs)
@@ -89,8 +91,8 @@ class ParamInfo(_SpecInfo):
 class MCPInfo(_SpecInfo):
     """Descriptor for configuring MCP server connections."""
 
-    server: Any = None
-    args: list[str] | None = None
+    server: MaybeRef[Any] = None
+    args: list[MaybeRef[str]] | None = None
     tools: list[str] | None = None
     exclude_tools: list[str] | None = None
     prefix: bool | str = True

{pyagentic_core-2.6.2rc1 → pyagentic_core-2.7.0a2}/pyagentic/_base/_spec.py

@@ -1,6 +1,6 @@
 from typing import Any, Callable, Literal
 
-from pyagentic._base._info import StateInfo, ParamInfo, AgentInfo, MCPInfo
+from pyagentic._base._info import StateInfo, ParamInfo, AgentInfo, MCPInfo, MaybeRef
 from pyagentic.policies._policy import Policy
 
 
@@ -141,9 +141,9 @@ class spec:
 
     @staticmethod
     def MCPLink(
-        server: Any = None,
+        server: MaybeRef[Any] = None,
         *,
-        args: list[str] | None = None,
+        args: list[MaybeRef[str]] | None = None,
         tools: list[str] | None = None,
         exclude_tools: list[str] | None = None,
         prefix: bool | str = True,
@@ -158,6 +158,10 @@ class spec:
           - ``str`` + ``args`` → stdio subprocess
           - ``FastMCP`` object → in-process
 
+        Both ``server`` and ``args`` entries may be StateRefs (e.g.
+        ``ref.self.root``); they are resolved against agent state when the
+        MCP connection is established.
+
         Args:
             server (Any): URL string, command string, or FastMCP server object.
             args (list[str], optional): Arguments for stdio subprocess mode.