Skip to main content
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

TypeDescriptionInput Method
Chat agentsInteractive, conversational agents--message "your question"
Sub agentsStructured input/output for pipelines--data-json '{"input": "..."}'

​
Running Agents

Run a pre-built agent: 
flipside agents run flipside/sql_agent --message "What are the top 10 DEXes by volume on Ethereum this week?"
Run a specific version: 
flipside agents run flipside/[email protected] --message "Show me gas trends"
Inject additional skills at runtime (useful for testing): 
flipside agents run flipside/my_agent --message "Analyze this data" --skill sql-querying,data-viz

​
Creating Custom Agents

Initialize a new agent: 
# 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: 
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: 
flipside agents push my_agent.yaml
After deployment, your agent is accessible as org/name (e.g., myorg/my_agent).

​
Agent Commands

CommandDescription
flipside agents listList 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: 
# 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:
LevelDescription
privateOnly you can access
organizationAll members of your org can access
publicAnyone can access