---
question: How do I attach an integration as agent tools?
kind: task
via_web: na
via_cli: na
via_python: available
via_api: na
via_config: na
ref_python: as_tools(configuration)
prereq: You need an integration with an `as_tools(configuration)` function, a credential [on the module configuration](/user-guide/build/integrations/add-credentials), and an agent class in the same in-engine module. See [Create an agent](/user-guide/build/agents/creating-an-agent).
next:
  - /capabilities/build/integrations/test-an-integration
  - /capabilities/build/agents/give-it-tools
---

# Use in an agent

An agent uses an integration through tools. By convention, each integration file defines a module-level `as_tools(configuration)` function that returns LangChain `StructuredTool`s. The `Integration` base class has no such method. The agent's `New()` builds the configuration from the module's settings, calls `as_tools`, and passes the tools to the agent constructor.

## Web UI

Not applicable. Agents added in Settings › Agents are workspace agents: a name, a system prompt and a model, with no tools. Wire an integration in the agent class with Python.

## CLI

Not applicable. No `abi` command adds tools to an agent. Write it in Python, then talk to the agent with `abi chat my_module MyAgent` to try the tools.

## Python

### Build the tools in New()

```python title="agents/MyAgent.py"
@classmethod
def New(
    cls,
    agent_shared_state: Optional[AgentSharedState] = None,
    agent_configuration: Optional[AgentConfiguration] = None,
) -> "MyAgent":
    from my_module import ABIModule
    from my_module.integrations.MyIntegration import (
        MyIntegrationConfiguration,
        as_tools,
    )

    tools: list = []
    api_key = ABIModule.get_instance().configuration.my_api_key
    if api_key:
        tools += as_tools(MyIntegrationConfiguration(api_key=api_key))
    ...
```

Import the integration inside `New()`, as above.

The `if api_key:` check matters only when the credential is optional. A field declared `my_api_key: str` and set to `{{ secret.MY_API_KEY }}` is always filled: when the secret is missing, the engine stops while it renders `config.yaml` (it asks for the value in a terminal and fails without one), before `New()` runs. To let the agent load without the integration, declare the field optional and leave it out of `config.yaml` until the key exists:

```python title="src/my_module/__init__.py"
class Configuration(ModuleConfiguration):
    my_api_key: str | None = None
```

The agent then starts without those tools, and gets them at the first restart after you add `my_api_key: "{{ secret.MY_API_KEY }}"` under the module's `config:`.

### Pass them to the agent

```python title="agents/MyAgent.py"
    return cls(
        name=cls.name,
        description=cls.description,
        chat_model=chat_model,
        tools=tools,
        agents=[],
        memory=None,
        state=agent_shared_state,
        configuration=agent_configuration,
    )
```

The rest of `New()` (the chat model, the system prompt) is on [Create an agent](/user-guide/build/agents/creating-an-agent?via=python).

### Try it

Restart the engine, then open a chat with the agent:

```bash
abi chat my_module MyAgent
```

Ask for something only the integration can answer. `abi chat` loads the engine, so in a NATS project it needs the broker (`abi dev up` or `abi stack start`).

## REST API

Not applicable. There is no HTTP call that adds tools to an agent. Once the agent is loaded, the engine API calls it with its tools: see [Create an agent](/user-guide/build/agents/creating-an-agent?via=api).

## Config

Not applicable. `config.yaml` holds the credential (see [Add credentials](/user-guide/build/integrations/add-credentials?via=config)), not the list of tools. The tools are wired in `New()`.

## Which tools the agent sees

`as_tools` decides the tool names, descriptions and argument schemas. The model picks a tool from its description, so write it for the model: what the tool does and when to use it. The tool schemas are on [Create an integration](/user-guide/build/agents/creating-an-integration#expose-it-as-tools). Workflows and other agents as tools are on [Give it tools](/user-guide/build/agents/give-it-tools).