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

# Agents

> Run AI-powered agents for blockchain data analysis and create your own custom agents

Agents are AI-powered assistants that can query blockchain data, generate SQL, and perform complex
analysis tasks. Run pre-built agents or create custom ones tailored to your needs.

## Agent Types

| Type            | Description                           | Input Method                |
| --------------- | ------------------------------------- | --------------------------- |
| **Chat agents** | Interactive, conversational agents    | `--message "your question"` |
| **Sub agents**  | Structured input/output for pipelines | `--data-json '...'`         |

## Running Agents

Run a pre-built agent:

```bash theme={null}
flipside agents run flipside/sql_agent --message "What are the top 10 DEXes by volume on Ethereum this week?"
```

Run a specific version:

```bash theme={null}
flipside agents run flipside/sql_agent@1.0.0 --message "Show me gas trends"
```

Inject additional skills at runtime (useful for testing):

```bash theme={null}
flipside agents run flipside/my_agent --message "Analyze this data" --skill sql-querying,data-viz
```

## Creating Custom Agents

Initialize a new agent:

```bash theme={null}
# Create a chat agent (default)
flipside agents init my_agent

# Create a sub agent for structured pipelines
flipside agents init my_agent --kind sub

# Specify the model
flipside agents init my_agent --model claude-4-5-haiku
```

This creates a YAML configuration file you can customize:

```yaml theme={null}
name: my_agent
kind: chat
model: claude-4-5-haiku
system_prompt: |
  You are a helpful blockchain data analyst...
skills:
  - sql-querying
  - data-visualization
```

## Deploying Agents

Push your agent configuration to deploy:

```bash theme={null}
flipside agents push my_agent.yaml
```

After deployment, your agent is accessible as `org/name` (e.g., `myorg/my_agent`).

## Agent Commands

| Command                                | Description                          |
| -------------------------------------- | ------------------------------------ |
| `flipside agents list`                 | List all agents in your organization |
| `flipside agents describe <name>`      | Show agent details                   |
| `flipside agents init <name>`          | Create new agent YAML config         |
| `flipside agents push <file.yaml>`     | Deploy or update an agent            |
| `flipside agents pull <name>`          | Download agent config as YAML        |
| `flipside agents run <name>`           | Execute an agent                     |
| `flipside agents validate <file.yaml>` | Validate agent configuration         |
| `flipside agents delete <name>`        | Delete a deployed agent              |

## Session Tracking

Agent runs automatically create sessions for trace capture:

```bash theme={null}
# Attach to an existing session
flipside agents run flipside/my_agent --message "Continue analysis" --session-id abc123

# Add custom metadata to the session
flipside agents run flipside/my_agent --message "Query" --meta '{"project": "defi-analysis"}'

# Set a session title
flipside agents run flipside/my_agent --message "Query" --title "DeFi Volume Analysis"
```

## Visibility Levels

Agents support three visibility levels:

| Level          | Description                        |
| -------------- | ---------------------------------- |
| `private`      | Only you can access                |
| `organization` | All members of your org can access |
| `public`       | Anyone can access                  |