> ## Documentation Index
> Fetch the complete documentation index at: https://splinter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> Individual agent configuration and execution

The `Agent` class represents an individual AI agent that can be executed.

## AgentBuilder

The recommended way to create agents is with `AgentBuilder`:

```python theme={null}
from splinter.workflow import AgentBuilder
from splinter.types import LLMProvider

agent = (
    AgentBuilder("researcher")
    .with_provider(LLMProvider.OPENAI, "gpt-4o")
    .with_system_prompt("Research topics. Output JSON.")
    .with_tools(["web_search"])
    .with_state_ownership(["research.*"])
    .build(gateway)
)
```

### AgentBuilder Methods

| Method                           | Description                  |
| -------------------------------- | ---------------------------- |
| `with_provider(provider, model)` | Set LLM provider and model   |
| `with_system_prompt(prompt)`     | Set system prompt            |
| `with_tools(tools)`              | Set allowed tools            |
| `with_state_ownership(patterns)` | Set state ownership patterns |
| `with_config(config)`            | Set full AgentConfig         |
| `build(gateway)`                 | Build the agent              |

## Agent Methods

### run()

Execute the agent.

```python theme={null}
async def run(
    task: str,
    context: dict[str, Any] | None = None,
) -> dict[str, Any]
```

| Parameter | Type           | Description              |
| --------- | -------------- | ------------------------ |
| `task`    | `str`          | What the agent should do |
| `context` | `dict \| None` | Additional context       |

```python theme={null}
result = await agent.run(task="Research AI trends")
result = await agent.run(
    task="Analyze this data",
    context={"data": [1, 2, 3]}
)
```

## AgentConfig

Configuration dataclass for agents:

```python theme={null}
from splinter.types import AgentConfig, LLMProvider

config = AgentConfig(
    agent_id="researcher",
    provider=LLMProvider.OPENAI,
    model="gpt-4o",
    system_prompt="Research topics. Output JSON.",
    tools=["web_search", "read_file"],
    state_ownership=["research.*"],
    max_steps=50,
    temperature=0.7,
)
```

### AgentConfig Fields

| Field             | Type          | Default  | Description              |
| ----------------- | ------------- | -------- | ------------------------ |
| `agent_id`        | `str`         | Required | Unique identifier        |
| `provider`        | `LLMProvider` | Required | LLM provider to use      |
| `model`           | `str`         | Required | Model name               |
| `system_prompt`   | `str`         | `""`     | System prompt            |
| `tools`           | `list[str]`   | `[]`     | Allowed tools            |
| `state_ownership` | `list[str]`   | `[]`     | State ownership patterns |
| `max_steps`       | `int \| None` | `None`   | Max steps for this agent |
| `temperature`     | `float`       | `0.7`    | Temperature              |

## LLMProvider

Supported providers:

```python theme={null}
from splinter.types import LLMProvider

LLMProvider.OPENAI      # OpenAI (GPT-4, GPT-4o)
LLMProvider.ANTHROPIC   # Anthropic (Claude)
LLMProvider.GEMINI      # Google (Gemini)
LLMProvider.GROK        # xAI (Grok)
```

## Full Example

```python theme={null}
from splinter.workflow import AgentBuilder
from splinter.gateway import Gateway
from splinter.types import ExecutionLimits, LLMProvider

# Create gateway with limits
gateway = Gateway(
    limits=ExecutionLimits(max_budget=10.0, max_steps=100)
)
gateway.configure_provider("openai", api_key="sk-...")

# Build agent
agent = (
    AgentBuilder("researcher")
    .with_provider(LLMProvider.OPENAI, "gpt-4o")
    .with_system_prompt("""
        You are a research assistant.
        Research the given topic thoroughly.
        Output your findings as JSON: {"findings": [...], "sources": [...]}
    """)
    .with_tools(["web_search"])
    .build(gateway)
)

# Run agent
result = await agent.run(task="Research AI trends for 2024")
print(result)
# {"findings": [...], "sources": [...]}
```