Agents

Agents are the core building blocks of Fluxgate AI. Learn how to create, configure, manage, and monitor your AI agents.

What Are Agents?

An agent is a configured AI assistant that combines a language model with tools, memory, and safety policies. Think of it as a "job description" for an AI — it defines what the AI should do, how it should behave, and what resources it has access to.

Why You Need Agents

Instead of making raw API calls to OpenAI or Anthropic, agents give you:

Versioning — Every config change creates a snapshot you can roll back to
Tool integration — Attach REST APIs, databases, or custom functions
Cost tracking — See exactly how much each agent costs per day/month
Safety policies — Enforce token limits, content filters, and approval gates
Run history — Full audit trail of every input, output, and tool call

Create an Agent (Dashboard)

Open the Agents Tab

Go to http://localhost:3000/dashboard and click 'Agents' in the sidebar.

Click 'Create Agent'

Click the button in the top-right corner to open the creation wizard.

Set Basic Info

Enter a unique name (lowercase, hyphens OK), description, and select your AI model.

Write System Prompt

Tell the AI how to behave. Be specific about its role, tone, and boundaries.

Attach Tools

Select any registered tools this agent should have access to. You can skip this and add tools later.

Add Tags

Add tags like 'production', 'support', 'v2' for organizing and filtering agents.

Click Create

Your agent is created with 'draft' status. Promote it via the Lifecycle tab when ready for production.

Create an Agent (API)

Create Agent via APIbash

curl -X POST http://localhost:8000/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent-v2",
    "description": "Customer support agent with knowledge base access",
    "model": "gpt-4o",
    "system_prompt": "You are a customer support specialist for TechCo. You help users with account issues, billing questions, and technical problems. Always be polite and provide step-by-step solutions. If you cannot resolve the issue, escalate to a human agent.",
    "tools": ["knowledge-search", "ticket-create"],
    "tags": ["support", "production", "v2"]
  }'

List All Agents

List Agentsbash

# List all agents
curl http://localhost:8000/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by tag
curl "http://localhost:8000/api/v1/agents?tag=production" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by status
curl "http://localhost:8000/api/v1/agents?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update an Agent

Updating an agent creates a new version. The previous version is preserved in the version history.

Update Agentbash

curl -X PUT http://localhost:8000/api/v1/agents/AGENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "Updated prompt with better instructions...",
    "model": "gpt-4o-mini"
  }'

Delete (Archive) an Agent

Archive Agentbash

# This archives the agent (soft delete). It can be restored later.
curl -X DELETE http://localhost:8000/api/v1/agents/AGENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Configuration Reference

Field	Type	Description
name	string	Unique identifier. Lowercase, hyphens allowed.
description	string	Human-readable description of the agent's purpose.
model	string	LLM model ID: gpt-4o, gpt-4o-mini, claude-3-sonnet, gemini-pro, etc.
system_prompt	string	Instructions for the AI. Defines behavior, tone, and boundaries.
tools	string[]	Array of tool IDs this agent can invoke.
tags	string[]	Labels for organizing and filtering agents.
max_tokens	number	Default max tokens per response. Override per-run.
temperature	number	Default temperature (0-1). Override per-run.

Best Practices

Use descriptive names: order-support-v2 not agent1
Start with a simple system prompt and iterate based on test results
Use tags to organize agents by team, environment, or use case
Always set budget limits before deploying to production
Test in the Simulation tab before promoting to "active"
Use the Prompt IDE tab for iterating on system prompts quickly

Model Selection Tips

Use gpt-4o or claude-3-opus for complex tasks requiring reasoning. Use gpt-4o-mini or claude-3-haiku for simple tasks to save costs. The Cost Optimizer can route automatically!

Dashboard Tour

Tools