Implemented a convenient way to use ACI.dev Tools in PydanticAI (#2093)

Co-authored-by: Douwe Maan <douwe@pydantic.dev>

Author: Kamal-Moha

docs/tools.md

@@ -721,11 +721,19 @@ def my_flaky_tool(query: str) -> str:
 ```
 Raising `ModelRetry` also generates a `RetryPromptPart` containing the exception message, which is sent back to the LLM to guide its next attempt. Both `ValidationError` and `ModelRetry` respect the `retries` setting configured on the `Tool` or `Agent`.
 
-## Use LangChain Tools {#langchain-tools}
+## Third-Party Tools
 
-If you'd like to use a tool from LangChain's [community tool library](https://python.langchain.com/docs/integrations/tools/) with PydanticAI, you can use the `pydancic_ai.ext.langchain.tool_from_langchain` convenience method. Note that PydanticAI will not validate the arguments in this case -- it's up to the model to provide arguments matching the schema specified by the LangChain tool, and up to the LangChain tool to raise an error if the arguments are invalid.
+### MCP Tools {#mcp-tools}
 
-Here is how you can use it to augment model responses using a LangChain web search tool. This tool will need you to install the `langchain-community` and `duckduckgo-search` dependencies to work properly.
+See the [MCP Client](./mcp/client.md) documentation for how to use MCP servers with Pydantic AI.
+
+### LangChain Tools {#langchain-tools}
+
+If you'd like to use a tool from LangChain's [community tool library](https://python.langchain.com/docs/integrations/tools/) with Pydantic AI, you can use the `pydancic_ai.ext.langchain.tool_from_langchain` convenience method. Note that Pydantic AI will not validate the arguments in this case -- it's up to the model to provide arguments matching the schema specified by the LangChain tool, and up to the LangChain tool to raise an error if the arguments are invalid.
+
+You will need to install the `langchain-community` package and any others required by the tool in question.
+
+Here is how you can use the LangChain `DuckDuckGoSearchRun` tool, which requires the `duckduckgo-search` package:
 
 ```python {test="skip"}
 from langchain_community.tools import DuckDuckGoSearchRun
@@ -737,15 +745,44 @@ search = DuckDuckGoSearchRun()
 search_tool = tool_from_langchain(search)
 
 agent = Agent(
-    'google-gla:gemini-2.0-flash',  # (1)!
+    'google-gla:gemini-2.0-flash',
     tools=[search_tool],
 )
 
-result = agent.run_sync('What is the release date of Elden Ring Nightreign?')  # (2)!
+result = agent.run_sync('What is the release date of Elden Ring Nightreign?')  # (1)!
 print(result.output)
 #> Elden Ring Nightreign is planned to be released on May 30, 2025.
 ```
 
+1. The release date of this game is the 30th of May 2025, which is after the knowledge cutoff for Gemini 2.0 (August 2024).
+
+### ACI.dev Tools {#aci-tools}
+
+If you'd like to use a tool from the [ACI.dev tool library](https://www.aci.dev/tools) with Pydantic AI, you can use the `pydancic_ai.ext.aci.tool_from_aci` convenience method. Note that Pydantic AI will not validate the arguments in this case -- it's up to the model to provide arguments matching the schema specified by the ACI tool, and up to the ACI tool to raise an error if the arguments are invalid.
+
+You will need to install the `aci-sdk` package, set your ACI API key in the `ACI_API_KEY` environment variable, and pass your ACI "linked account owner ID" to the function.
+
+Here is how you can use the ACI.dev `TAVILY__SEARCH` tool:
+
+```python {test="skip"}
+import os
+
+from pydantic_ai import Agent
+from pydantic_ai.ext.aci import tool_from_aci
+
+tavily_search = tool_from_aci(
+    'TAVILY__SEARCH',
+    linked_account_owner_id=os.getenv('LINKED_ACCOUNT_OWNER_ID')
+)
+
+agent = Agent(
+    'google-gla:gemini-2.0-flash',
+    tools=[tavily_search]
+)
+
+result = agent.run_sync('What is the release date of Elden Ring Nightreign?')  # (1)!
+print(result.output)
+#> Elden Ring Nightreign is planned to be released on May 30, 2025.
+```
 
-1. While this task is simple Gemini 1.5 didn't want to use the provided tool. Gemini 2.0 is still fast and cheap.
-2. The release date of this game is the 30th of May 2025, which was confirmed after the knowledge cutoff for Gemini 2.0 (August 2024).
+1. The release date of this game is the 30th of May 2025, which is after the knowledge cutoff for Gemini 2.0 (August 2024).

pydantic_ai_slim/pydantic_ai/ext/aci.py

@@ -0,0 +1,66 @@
+# Checking whether aci-sdk is installed
+try:
+    from aci import ACI
+except ImportError as _import_error:
+    raise ImportError('Please install `aci-sdk` to use ACI.dev tools') from _import_error
+
+from typing import Any
+
+from aci import ACI
+
+from pydantic_ai import Tool
+
+
+def _clean_schema(schema):
+    if isinstance(schema, dict):
+        # Remove non-standard keys (e.g., 'visible')
+        return {k: _clean_schema(v) for k, v in schema.items() if k not in {'visible'}}
+    elif isinstance(schema, list):
+        return [_clean_schema(item) for item in schema]
+    else:
+        return schema
+
+
+def tool_from_aci(aci_function: str, linked_account_owner_id: str) -> Tool:
+    """Creates a Pydantic AI tool proxy from an ACI function.
+
+    Args:
+        aci_function: The ACI function to wrao.
+        linked_account_owner_id: The ACI user ID to execute the function on behalf of.
+
+    Returns:
+        A Pydantic AI tool that corresponds to the ACI.dev tool.
+    """
+    aci = ACI()
+    function_definition = aci.functions.get_definition(aci_function)
+    function_name = function_definition['function']['name']
+    function_description = function_definition['function']['description']
+    inputs = function_definition['function']['parameters']
+
+    json_schema = {
+        'additionalProperties': inputs.get('additionalProperties', False),
+        'properties': inputs.get('properties', {}),
+        'required': inputs.get('required', []),
+        # Default to 'object' if not specified
+        'type': inputs.get('type', 'object'),
+    }
+
+    # Clean the schema
+    json_schema = _clean_schema(json_schema)
+
+    def implementation(*args: Any, **kwargs: Any) -> str:
+        if args:
+            raise TypeError('Positional arguments are not allowed')
+        return aci.handle_function_call(
+            function_name,
+            kwargs,
+            linked_account_owner_id=linked_account_owner_id,
+            allowed_apps_only=True,
+        )
+
+    return Tool.from_schema(
+        function=implementation,
+        name=function_name,
+        description=function_description,
+        json_schema=json_schema,
+    )

pydantic_ai_slim/pydantic_ai/ext/langchain.py

@@ -27,13 +27,13 @@ def run(self, *args: Any, **kwargs: Any) -> str: ...
 
 
 def tool_from_langchain(langchain_tool: LangChainTool) -> Tool:
-    """Creates a Pydantic tool proxy from a LangChain tool.
+    """Creates a Pydantic AI tool proxy from a LangChain tool.
 
     Args:
         langchain_tool: The LangChain tool to wrap.
 
     Returns:
-        A Pydantic tool that corresponds to the LangChain tool.
+        A Pydantic AI tool that corresponds to the LangChain tool.
     """
     function_name = langchain_tool.name
     function_description = langchain_tool.description

pyproject.toml

@@ -180,6 +180,7 @@ executionEnvironments = [
 exclude = [
     "examples/pydantic_ai_examples/weather_agent_gradio.py",
     "mcp-run-python/node_modules",
+    "pydantic_ai_slim/pydantic_ai/ext/aci.py", # aci-sdk requires Python 3.10+ so cannot be added as an (optional) dependency
 ]
 extraPaths = ["mcp-run-python/stubs"]
 
@@ -219,7 +220,11 @@ include = [
     # "fasta2a/**/*.py",
     "tests/**/*.py",
 ]
-omit = ["tests/test_live.py", "tests/example_modules/*.py"]
+omit = [
+    "tests/test_live.py",
+    "tests/example_modules/*.py",
+    "pydantic_ai_slim/pydantic_ai/ext/aci.py", # aci-sdk requires Python 3.10+ so cannot be added as an (optional) dependency
+]
 branch = true
 
 # https://coverage.readthedocs.io/en/latest/config.html#report
@@ -265,4 +270,4 @@ skip = '.git*,*.svg,*.lock,*.css,*.yaml'
 check-hidden = true
 # Ignore "formatting" like **L**anguage
 ignore-regex = '\*\*[A-Z]\*\*[a-z]+\b'
-ignore-words-list = 'asend'
+ignore-words-list = 'asend,aci'