diff --git a/content/changelog/0.1.1.md b/content/changelog/0.1.1.md new file mode 100644 index 0000000..9d6d223 --- /dev/null +++ b/content/changelog/0.1.1.md @@ -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. diff --git a/content/docs/core-concepts/tools.md b/content/docs/core-concepts/tools.md index b1bfd1f..5b5c2f0 100644 --- a/content/docs/core-concepts/tools.md +++ b/content/docs/core-concepts/tools.md @@ -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. diff --git a/content/docs/guides/dynamic-tools-and-mcp.md b/content/docs/guides/dynamic-tools-and-mcp.md new file mode 100644 index 0000000..1cb3256 --- /dev/null +++ b/content/docs/guides/dynamic-tools-and-mcp.md @@ -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. diff --git a/content/docs/guides/error-handling.md b/content/docs/guides/error-handling.md index b66be60..e134f08 100644 --- a/content/docs/guides/error-handling.md +++ b/content/docs/guides/error-handling.md @@ -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) ``` diff --git a/content/docs/reference/agent-api.md b/content/docs/reference/agent-api.md index f1afb21..cd915f0 100644 --- a/content/docs/reference/agent-api.md +++ b/content/docs/reference/agent-api.md @@ -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: ''")` 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. diff --git a/content/docs/reference/errors.md b/content/docs/reference/errors.md index 3c42b42..f894c9b 100644 --- a/content/docs/reference/errors.md +++ b/content/docs/reference/errors.md @@ -7,16 +7,19 @@ 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 @@ -24,7 +27,7 @@ The loop draws a clear line between failures the model can fix and failures your **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 diff --git a/src/lib/site.ts b/src/lib/site.ts index 60dd156..b87d30a 100644 --- a/src/lib/site.ts +++ b/src/lib/site.ts @@ -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";