Agents — Your AI Workforce

An Agent is a named AI worker configured with a role, goal, and backstory. These three fields are injected into the LLM system prompt to shape how the model reasons and responds.

Scenario: An e-commerce team runs three agents: a "Product Researcher" who finds trending items, a "Copywriter" who writes listing descriptions, and a "Quality Checker" who flags inaccurate claims.

Role, Goal, and Backstory

These three fields determine the agent's identity inside the LLM context window:

Role

The agent's job title. Establishes authority and scope. Example: "Senior Product Researcher"

Goal

What the agent is trying to achieve. Guides task selection and output format. Example: "Find the top 10 trending products in the electronics category and return a ranked list with rationale."

Backstory

Persona detail that sets tone, expertise level, and communication style. Example: "You have 8 years of experience in consumer electronics retail. You make data-driven recommendations backed by market trends."

Provider selection

Each agent can use a different LLM. FleetQ supports Anthropic (Claude), OpenAI (GPT-4o), Google (Gemini), and local agents (Claude Code, Codex). If you leave it as Default, FleetQ inherits the team-level setting.

Local agents (Claude Code, Codex) are auto-detected on the host machine and cost zero credits. They're perfect for development and testing without consuming your API budget.

Resolution hierarchy (highest to lowest priority):

Skill → Agent → Team → Platform default

If a skill specifies its own model, that takes precedence over the agent's setting.

Attaching skills and tools

From the agent detail page, add Skills (reusable AI capabilities) and Tools (MCP servers, built-in bash/filesystem/browser). At inference time, FleetQ injects these into the LLM call automatically.

Health checks (behind the scenes)

Every 5 minutes, the platform runs a silent health check on all active agents. If an agent fails (e.g. the underlying model is unreachable), its status is set to degraded. Degraded agents are flagged in the UI and excluded from new experiment assignments until a subsequent health check passes. Healthy agents show no indicator.

Heartbeat scheduling

Agents can be configured to run automatically on a cron schedule without being attached to an experiment. This is useful for monitoring tasks, periodic data pulls, and background automation that should run independently of user-triggered workflows.

Configure a heartbeat via the heartbeat_definition field when creating or updating an agent:

json

// PUT /api/v1/agents/AGENT_ID
{
  "heartbeat_definition": {
    "enabled": true,
    "cron": "0 * * * *",
    "prompt": "Check the latest competitor pricing and store any changes in memory."
  }
}

Field	Description
enabled	Boolean. Set to `false` to pause the schedule without removing the configuration.
cron	Standard 5-field cron expression. Default: `0 * * * *` (every hour).
prompt	The task prompt sent to the agent on each heartbeat tick.
next_run_at	Read-only. Timestamp of the next scheduled execution. Computed automatically from the cron expression.

Heartbeat runs are dispatched by ExecuteAgentHeartbeatJob and consume credits from the team budget like any other agent execution. Use max_credits or budget alerts to cap spend.

Disabling an agent

Soft-disabling an agent prevents it from being used in new experiments. Existing running experiments are not affected. Re-enable at any time from the agent detail page or via:

bash

curl -X PATCH https://fleetq.169.58.89.204.sslip.io/api/v1/agents/AGENT_ID/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"status": "disabled"}'

Configuration history & rollback

Every change to an agent's configuration (role, goal, backstory, skills, tools, provider) is versioned. View the full history from the agent detail page or via GET /api/v1/agents/{id}/config-history.

To revert to a previous version, use Rollback on the detail page or call POST /api/v1/agents/{id}/rollback with the version number. This is useful when a prompt tweak causes regressions — roll back instantly without manual re-editing.

Runtime state

Check an agent's current runtime state — active experiments, queue depth, recent execution history — via GET /api/v1/agents/{id}/runtime-state or the agent_runtime_state MCP tool.

Agent templates

Browse pre-built agent templates from the Marketplace via agent_templates_list MCP tool. Install a template to get a fully configured agent with role, goal, backstory, skills, and tools.

MCP tools

Tool	Purpose
agent_list	List agents with filtering and pagination
agent_get	Get agent details including skills and tools
agent_create	Create a new agent
agent_update	Update agent configuration
agent_toggle_status	Enable or disable an agent
agent_delete	Soft-delete an agent
agent_config_history	View configuration version history
agent_rollback	Revert to a previous configuration version
agent_runtime_state	Check active experiments, queue depth, recent runs
agent_skill_sync	Sync skills attached to an agent
agent_tool_sync	Sync tools attached to an agent
agent_templates_list	Browse pre-built agent templates

API endpoints

Method	Path	Purpose
GET	/api/v1/agents	List agents
GET	/api/v1/agents/{id}	Get agent details
POST	/api/v1/agents	Create agent
PUT	/api/v1/agents/{id}	Update agent
DELETE	/api/v1/agents/{id}	Delete agent
PATCH	/api/v1/agents/{id}/status	Toggle status
GET	/api/v1/agents/{id}/config-history	Configuration history
POST	/api/v1/agents/{id}/rollback	Rollback to version
GET	/api/v1/agents/{id}/runtime-state	Runtime state

See also: Skills (reusable capabilities), Tools (MCP servers & built-in tools), Crews (multi-agent teams).