Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions content/changelog/0.1.1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
version: 0.1.1
title: Dynamic tools
releaseDate: 2026-10-29
tags:
- Added
- Fixed
- Changed
---

Tools whose schemas come from somewhere else (an MCP server, an OpenAPI spec, a plugin) now work, and a running session can gain or lose tools.

### Added

- `AgentSession.add_tools(tools, replace=False)` and `AgentSession.remove_tools(names)` change a live session's tools. The model sees the change from its next call. Each call is all or nothing, and `final_answer` (plus `load_skill` when skills are configured) can't be removed or replaced.
- `Tool.validate_arguments` (default `True`) and the matching `@tool(validate_arguments=...)` option, for tools whose arguments are validated elsewhere.
- `Tool.validate(arguments)`, a public way to check arguments without running the tool. `call()` now goes through it.
- `examples/cli_dynamic_tools.py`, and a [Dynamic tools and MCP](/docs/guides/dynamic-tools-and-mcp) guide with an MCP bridge recipe. agentling still has no MCP dependency.

### Fixed

- A property whose `type` is a list, such as `["string", "null"]`, no longer crashes validation. A value passes if it matches any listed type, and `"null"` matches `None`.
- A schema with no `properties` no longer rejects every argument.
- Extra arguments are rejected only when `additionalProperties` is `false`.
- Validation skips keywords it doesn't implement (`anyOf`, `$ref`, `format`, nested objects) and only ever raises `ToolCallError`.

### Changed

- Tool names and schemas are checked wherever a tool is registered, not only in `@tool`. A `Tool` subclass with an invalid name or a non-object schema now fails with `ValueError` at registration.
- A `Tool` subclass whose schema doesn't set `"additionalProperties": false` now accepts extra arguments, as JSON Schema intends. `@tool` schemas still reject them.
- Loading a skill that declares a tool whose name is taken by a different tool now returns an error to the model instead of silently keeping the existing tool.
- Docstrings and the [Errors reference](/docs/reference/errors) now say which errors are reserved and not yet raised, and that provider errors reach your code unwrapped.
42 changes: 41 additions & 1 deletion content/docs/core-concepts/tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,53 @@ Supported parameter types map directly to JSON Schema: `str`, `int`, `float`, `b

If the model sends arguments that do not match the schema, a missing required field, a wrong type, or an unknown key, the tool raises a `ToolCallError` which the loop feeds back to the model as an error observation. The model gets a chance to fix its call rather than the run blowing up. See [Error handling](/docs/guides/error-handling) for the full recovery story.

Tool names may contain letters, digits, underscores and hyphens, up to 64 characters, and `parameters` must be a JSON Schema object (`"type": "object"`). Both are checked when the tool is registered, so a bad name fails straight away with a `ValueError`.

## Tools from a JSON Schema

A tool doesn't have to start as a Python function. When the schema comes from somewhere else, such as an MCP server, an OpenAPI spec or a plugin, subclass `Tool` and set `name`, `description` and `parameters` yourself:

```python
from typing import Any

from agentling import Tool


class WeatherTool(Tool):
name = "get_weather"
description = "Get the current weather for a city."
parameters = {
"type": "object",
"properties": {
"city": {"type": "string"},
"units": {"type": ["string", "null"]},
},
"required": ["city"],
}

async def forward(self, **kwargs: Any) -> str:
...
```

agentling checks arguments against a small, forgiving subset of JSON Schema:

- `required` fields must be present.
- A property's `type` may be one name or a list (`["string", "null"]`); the value must match one of them, and `"null"` matches `None`.
- `enum` values are enforced.
- Extra arguments are rejected only when `additionalProperties` is `false`. Schemas generated by `@tool` set it; schemas from elsewhere often don't.
- Anything else (`anyOf`, `$ref`, `format`, nested objects) is not checked, so a call the real schema allows is never refused.

When something else owns validation, such as a remote server, set `validate_arguments = False` on the class (or `@tool(validate_arguments=False)`). The arguments still have to be a JSON object, but the schema checks are skipped and `forward` receives them as sent. `tool.validate(arguments)` runs the checks without calling the tool, and does nothing when `validate_arguments` is `False`.

To add or remove tools on a running session, see [Dynamic tools and MCP](/docs/guides/dynamic-tools-and-mcp).

## The built-in final_answer tool

Every agent has a built-in `final_answer` tool. The model can call it to end the run explicitly, or it can just reply with plain text; both terminate the run. See [The Agent Loop](/docs/core-concepts/agent-loop) for how termination works.

## Per-tool metadata

Tools carry their own execution metadata: a per-call `timeout`, a `parallel_safe` flag, and `max_output_chars` to bound how much of the result reaches the model.
Tools carry their own execution metadata: a per-call `timeout`, a `parallel_safe` flag, `max_output_chars` to bound how much of the result reaches the model, and `validate_arguments` to turn off the local schema checks.

> [!WARNING]
> A timeout stops the agent from waiting on a tool and turns it into an observation, but a synchronous tool already running in a thread cannot be forcibly cancelled and will finish in the background. Prefer async tools, or make blocking tools cooperative, when timeouts matter.
Expand Down
95 changes: 95 additions & 0 deletions content/docs/guides/dynamic-tools-and-mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
title: Dynamic tools and MCP
slug: dynamic-tools-and-mcp
description: Add and remove tools on a running session, and wrap tools from an MCP server as agentling tools.
order: 6
---

Some tools aren't known when you build the agent. A user connects an app halfway through a conversation, a server changes the tools it offers, or a plugin loads late. agentling lets a running session gain and lose tools, and it accepts tools whose JSON Schema came from somewhere else.

## Adding and removing tools

Every session has its own tool set. Change it with `add_tools` and `remove_tools`:

```python
session = agent.start()
await session.run("What's on my calendar?")

session.add_tools([list_events, create_event])
await session.run("Book lunch with Ada on Friday.", reset=False)

session.remove_tools(["create_event"])
```

The model sees a change from its next call. That includes a run that is already going: if a step callback or another task adds a tool after step one, the model can use it in step two.

Both methods are all or nothing. If any tool in the batch has a bad name, a non-object schema, or a name that is already taken, nothing changes and you get a `ValueError`. Pass `replace=True` to swap in a new definition for a name you already added, for example when a server sends an updated schema.

If the model calls a tool you removed, it gets an unknown-tool observation and carries on. Saved memory that mentions a removed tool still loads and continues normally.

See the [Agent API](/docs/reference/agent-api) for the exact rules, and `examples/cli_dynamic_tools.py` for a runnable demo.

## Tools from someone else's schema

A tool from an MCP server, an OpenAPI spec or a plugin arrives as a name, a description and a JSON Schema. Subclass `Tool` and set those three yourself. agentling's argument checks handle real-world schemas: union types such as `["string", "null"]`, missing `properties`, and open objects. Keywords it doesn't implement are left alone rather than rejected. See [Tools](/docs/core-concepts/tools) for the full list.

When the other side validates arguments anyway, set `validate_arguments = False` so the local check never refuses a call the server would accept.

## Recipe: an MCP bridge

agentling has no MCP dependency. This recipe uses the official [MCP Python SDK](https://pypi.org/project/mcp/) (`pip install "mcp>=2.3,<3"`) in your own code to wrap each tool on an MCP server as an agentling `Tool`:

```python
import hashlib
import re
from typing import Any

from mcp import Client

from agentling import Agent, OpenAIModel, Tool


def safe_name(prefix: str, name: str) -> str:
full = re.sub(r"[^A-Za-z0-9_-]", "_", f"{prefix}__{name}")
if len(full) <= 64:
return full
return f"{full[:55]}_{hashlib.sha256(full.encode()).hexdigest()[:8]}"


class McpTool(Tool):
"""One tool on an MCP server, callable from agentling."""

# The server checks arguments against its own schema.
validate_arguments = False

def __init__(self, client: Client, remote: Any, prefix: str) -> None:
self._client = client
self._remote_name = remote.name
self.name = safe_name(prefix, remote.name)
self.description = remote.description or ""
self.parameters = remote.input_schema

async def forward(self, **kwargs: Any) -> str:
result = await self._client.call_tool(self._remote_name, kwargs)
text = "\n".join(item.text for item in result.content if item.type == "text")
if result.is_error:
raise RuntimeError(text)
return text


async def main() -> None:
async with Client("https://mcp.example.com/mcp") as client:
listed = await client.list_tools()
session = Agent(model=OpenAIModel("gpt-4o-mini")).start()
session.add_tools(McpTool(client, tool, "example") for tool in listed.tools)

print(await session.run("Use the example server to answer this."))
```

A few things to handle in real use:

- **Names.** `safe_name` keeps tool names within agentling's rules (letters, digits, `_` and `-`, up to 64 characters) and prefixes them with the server name so two servers can't collide.
- **Schemas.** If a server's `input_schema` lacks `"type": "object"`, wrap it in `{"type": "object", "properties": {}}`, or registration fails.
- **Changing tool lists.** When a server reports that its tools changed, list them again and call `add_tools(..., replace=True)` for new or updated tools and `remove_tools(...)` for ones that disappeared.
- **Errors and results.** Raising inside `forward` turns into an error observation the model can recover from. Non-text content, such as images, needs your own handling. Newer servers may also ask for more input mid-call; see the SDK docs.
- **Trust.** A tool's description and output come from the server. Treat them as untrusted input, and put anything that can change data behind your own approval step.
6 changes: 4 additions & 2 deletions content/docs/guides/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,14 +51,16 @@ Tool output and error messages are fed back into the model's context, so two kno

## The exception hierarchy

Everything the framework raises derives from `AgentlingError`, with domain subclasses such as `ToolCallError`, `ModelError`, and `MemoryLoadError`. Catch the base class for a blanket handler, or the subclass you care about:
agentling's own errors derive from `AgentlingError`, with subclasses such as `ToolCallError`, `ModelError`, and `MemoryLoadError`. Provider errors (for example `openai.APIError`, after retries) are not wrapped, so catch them too if you want one handler for a failed run:

```python
import openai

from agentling import AgentlingError

try:
answer = await agent.run(task)
except AgentlingError as exc:
except (AgentlingError, openai.APIError) as exc:
logger.error("agent run failed: %s", exc)
```

Expand Down
26 changes: 25 additions & 1 deletion content/docs/reference/agent-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,4 +68,28 @@ print(session.memory.steps) # typed steps recorded so far
session.interrupt() # request a graceful stop
```

The session owns the per-run state: the `Memory` of typed steps, the interrupt token, and any skill tools loaded during a run. See [Sessions and concurrency](/docs/guides/sessions-and-concurrency) and [Interruption](/docs/guides/interruption) for the patterns built on top of it.
The session owns the per-run state: the `Memory` of typed steps, the interrupt token, and its own tool set, including any skill tools loaded during a run. See [Sessions and concurrency](/docs/guides/sessions-and-concurrency) and [Interruption](/docs/guides/interruption) for the patterns built on top of it.

## session.add_tools() and session.remove_tools()

```python
session.add_tools([create_issue, search_issues])
session.add_tools([updated_search_issues], replace=True)
session.remove_tools(["create_issue"])
```

These change one session's tools. The agent and other sessions are not affected. The model sees the change from its next call, which can be the next step of a run that is already going.

`add_tools(tools, *, replace=False)`

- Checks every tool first and adds nothing if any check fails.
- Raises `ValueError` when a name is invalid, a schema isn't an object, a name appears twice in `tools`, or a name is already in the session and `replace` is `False`.
- With `replace=True`, a tool with an existing name takes the old one's place, keeping its position in the list the model sees.

`remove_tools(names)`

- Removes the named tools. A name given twice is removed once.
- Raises `ValueError("Unknown tool: '<name>'")` and removes nothing if any name isn't in the session.
- If the model later calls a removed tool, it gets an unknown-tool observation and can carry on.

Both refuse the built-in tools: `final_answer`, and `load_skill` when the agent has skills. Change tools through these methods rather than editing `session.tools` directly.
15 changes: 9 additions & 6 deletions content/docs/reference/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,24 +7,27 @@ metaTitle: "Errors reference: the exception hierarchy"
metaDescription: "Every exception under AgentlingError, which failures the loop recovers from on its own, and what redact_errors changes about what the model sees."
---

Every exception agentling raises lives under a single base class, `AgentlingError`, so one `except` clause can catch anything the framework produces. Just as important is what does not raise: most tool failures are converted into observations the model can recover from instead of crashing the run.
agentling's own errors share one base class, `AgentlingError`. Other exceptions can still reach your code: `ValueError` or `TypeError` for bad configuration (an invalid tool name, a bad SKILL.md field), `yaml.YAMLError` for SKILL.md frontmatter that doesn't parse, and the provider SDK's own errors (such as `openai.APIError`) once retries are used up. Just as important is what does not raise: most tool failures become observations the model can recover from.

## The hierarchy

| Exception | Raised when |
| --- | --- |
| `AgentlingError` | The base class for every framework error. Catch this to handle anything below. |
| `ToolCallError` | The model sends arguments that do not match a tool's schema: a missing required field, a wrong type, or an unknown key. |
| `ModelError` | A model turn fails permanently, or exceeds `model_timeout`. |
| `MemoryLoadError` | `Memory.load_json` receives data that fails validation and cannot be rebuilt into typed steps. |
| `AgentlingError` | The base class for agentling's own errors. |
| `ToolCallError` | A tool gets bad arguments: a missing required field, a wrong type, a value outside `enum`, or an extra key the schema forbids. Tools may also raise it themselves. The loop shows it to the model. |
| `ModelError` | A model turn exceeds `model_timeout`, or the model keeps sending tool calls that can't be parsed. |
| `ModelOutputError` | A tool call can't be parsed. The loop catches it and asks the model to try again, up to twice, before raising `ModelError`. |
| `ToolTimeoutError` | A tool runs past its timeout. It is not raised: it words the observation the model sees. |
| `MemoryLoadError` | Saved memory has an unknown version or a bad shape. Invalid JSON passed to `Memory.load_json` raises `json.JSONDecodeError` instead. |
| `AgentRunError`, `ToolExecutionError`, `SkillLoadError` | Reserved. agentling doesn't raise these yet; they are exported so your code can catch them once it does. |

## Observations, not crashes

The loop draws a clear line between failures the model can fix and failures your code must handle.

**Fed back to the model as observations.** Anything that goes wrong inside a tool call becomes a `ToolResult` with `is_error=True`, tagged by kind. That includes a `ToolCallError` from invalid arguments, an exception raised by the tool body, a tool timeout, and a call to an unknown tool. The observation carries a hint matched to the failure: an invalid-argument error says "Fix the arguments and try again", while an execution, timeout, or unknown-tool error says "Consider a different approach or tool". The model gets a chance to correct course, and one bad tool call does not kill the run. See [Error handling](/docs/guides/error-handling) for the practical patterns.

**Raised to the caller.** Failures the model cannot repair surface as exceptions in your code: a `ModelError` when the provider fails permanently or a turn exceeds its time budget, and a `MemoryLoadError` when saved memory does not validate on load.
**Raised to the caller.** Failures the model can't repair reach your code as exceptions: a `ModelError` when a turn exceeds its time budget or the model keeps sending unparseable tool calls, the provider SDK's error when its retries are used up, and a `MemoryLoadError` when saved memory doesn't validate on load.

## redact_errors

Expand Down
2 changes: 1 addition & 1 deletion src/lib/site.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
export const SITE_NAME = "Agentling";
/** Latest released version, shown in the header. */
export const VERSION = "0.1.0";
export const VERSION = "0.1.1";
export const SITE_TAGLINE =
"An async Python agent loop you can read in an afternoon. Typed memory, streamed events, and tools that are plain functions.";
export const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://agentling.dev";
Expand Down
Loading