# AI Agent

> Give an AI a task, files to read and tools to use, and use what it hands back.

Built-in step · 1 step. Web page: https://docs.lodol.com/docs/integrations/built-in/agent

To learn when to use these steps, with examples, read [Use an AI agent](https://docs.lodol.com/docs/guides/ai-agents.md).

## Steps

### Run an AI agent

Give an AI a task, files to read and tools to use. It works out which tools to use and when, then hands back an answer or the exact fields you ask for. For work with no fixed recipe, such as reading an invoice or researching a name.

**Inputs**

- Task (`task`, text, required): What the agent should do this run. Write it as you would brief a colleague, and mention the values it needs from earlier steps.
- Model (`model`, text, required): The model that runs the agent, from Anthropic, OpenAI, Google Gemini or another AI provider you have connected under Integrations. It runs on your own API key, billed by the provider to your account; Lodol supplies the agent, not the model. One of: `anthropic/claude-opus-4-8` (Claude Opus 4.8 (recommended)), `anthropic/claude-fable-5` (Claude Fable 5 (most capable, expensive)), `anthropic/claude-sonnet-5` (Claude Sonnet 5), `anthropic/claude-haiku-4-5` (Claude Haiku 4.5 (fastest, lowest cost)), `openai/gpt-6-astra` (GPT-6 Astra (most capable)), `openai/gpt-6.1-sol` (GPT-6.1 Sol (near-Astra quality, lower cost)), `openai/gpt-6-luna` (GPT-6 Luna (fastest, lowest cost)), `openai/gpt-5.5` (GPT-5.5), `openai/gpt-5.4` (GPT-5.4), `openai/gpt-5.4-mini` (GPT-5.4 mini), and 35 more.
- Files (`files`, list): PDFs or images for the agent to read along with the task, such as an invoice, a CV or a screenshot. Upload one, or use a file from an earlier step. Needs a model from Anthropic, OpenAI or Google Gemini.
- Instructions (`instructions`, text): Standing rules for every run: who the work is for, what a good answer looks like, what to leave out. The place for the context a client or a team needs applied.
- Tools (`tools`, list): What the agent may use: actions from your apps, such as a web search or reading a page, and your own published workflows. They run with this workspace's connections, so connect the app first. Fix any input you do not want the agent to choose, such as which spreadsheet to write to. Keep the list short and relevant.
- Fields to return (`output_schema`, object): The fields the agent must fill in before it finishes, each with a note on what it should hold. Later steps then read them by name. Leave empty to get a plain text answer instead.
- Turn limit (`max_steps`, number): The most turns the agent may take before it has to finish. Each turn is one model call and may use one or more tools. From 1 to 30. Default: `10`.
- Fallback model (`fallback_model`, text): A second model to carry on with if the first one fails to answer, such as during an outage or a rate limit. Chosen from the same list as the model, and run on your own key for it in the same way. One of: `anthropic/claude-opus-4-8` (Claude Opus 4.8 (recommended)), `anthropic/claude-fable-5` (Claude Fable 5 (most capable, expensive)), `anthropic/claude-sonnet-5` (Claude Sonnet 5), `anthropic/claude-haiku-4-5` (Claude Haiku 4.5 (fastest, lowest cost)), `openai/gpt-6-astra` (GPT-6 Astra (most capable)), `openai/gpt-6.1-sol` (GPT-6.1 Sol (near-Astra quality, lower cost)), `openai/gpt-6-luna` (GPT-6 Luna (fastest, lowest cost)), `openai/gpt-5.5` (GPT-5.5), `openai/gpt-5.4` (GPT-5.4), `openai/gpt-5.4-mini` (GPT-5.4 mini), and 35 more.
- Conversation key (`memory_key`, text): Give runs that belong to one conversation the same key, such as a chat thread id or a customer's email, and the agent sees what was asked and answered in the earlier runs. Leave empty and each run starts fresh.
- Runs to remember (`memory_window`, number): How many earlier runs under the same conversation key the agent is shown. From 1 to 50. Default: `10`.

**Outputs**

- `model` (text): The model that finished the run.
- `output` (object): The fields asked for, filled in; or the agent's final text when no fields were asked for.
- `steps` (number): How many turns the agent took.
- `text` (text): The agent's final message.
- `tool_calls` (list): Each tool the agent used, with its input, whether it succeeded, and the start of what came back.
- `usage` (object): The tokens the run used.

**Example output**

```json
{
  "model": "example_value",
  "output": {},
  "steps": 1,
  "text": "example_value",
  "tool_calls": [],
  "usage": {
    "input_tokens": 1,
    "output_tokens": 1
  }
}
```