---
question: Where does an integration live in a module?
kind: overview
---

# Integrations

An integration is one external API, wrapped in a Python class under a module's `integrations/` folder. It handles authentication and HTTP, and returns the service's data. Agents call it as tools, pipelines turn its data into RDF, and workflows build on it. `abi new integration` scaffolds the class inside an in-engine module.

<!-- matrix -->

Nexus has no screen for integrations, and the API process has no integration routes. An integration is code you write, test and wire in Python. The Web UI and the REST API only reach its credentials, through the engine secret service.

## Key concepts

- **Integration class.** A subclass of `Integration` (`naas_abi_core.integration`) with a configuration dataclass that holds the key and the base URL. One class per external service.
- **`as_tools(configuration)`.** A module-level function in the integration file, by convention. It returns LangChain `StructuredTool`s that an agent adds in its `New()`. The base class has no such method.
- **Credentials.** A field on the module's `Configuration`, set in `config.yaml` as `{{ secret.MY_API_KEY }}`. The engine secret service fills it at startup, from `.env` by default. Nexus workspace secrets do not.
- **No side effects.** An integration does not write to the triple store, call other modules, or hold business logic. Pipelines and workflows do that with its data.
- **In-engine only.** `abi new integration` refuses to run inside a remote module. There, call the API from plain Python (`httpx`, `requests`) with credentials from `self.engine.services.secret`.

```text
External API  →  Integration  →  Pipeline (transforms to RDF)
                              →  Workflow (business logic)
                              →  Agent tool (direct invocation by the model)
```