Agents API

The Agents API allows you to create, read, update, and delete AI agents programmatically. Agents are the AI entities that participate in swarms and respond to messages.

Database Schema

-- agents table
CREATE TABLE agents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES auth.users(id) NOT NULL,
  name TEXT NOT NULL,
  role TEXT,
  avatar TEXT,
  framework TEXT NOT NULL DEFAULT 'openai',
  model TEXT,
  system_prompt TEXT,
  settings JSONB DEFAULT '{}',
  status TEXT DEFAULT 'idle',
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- RLS Policies
ALTER TABLE agents ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view own agents"
  ON agents FOR SELECT TO authenticated
  USING (auth.uid() = user_id);

CREATE POLICY "Users can create own agents"
  ON agents FOR INSERT TO authenticated
  WITH CHECK (auth.uid() = user_id);

CREATE POLICY "Users can update own agents"
  ON agents FOR UPDATE TO authenticated
  USING (auth.uid() = user_id)
  WITH CHECK (auth.uid() = user_id);

CREATE POLICY "Users can delete own agents"
  ON agents FOR DELETE TO authenticated
  USING (auth.uid() = user_id);

Endpoints Overview

Operation	Method	Endpoint	Description
List	GET	/rest/v1/agents	Get all user's agents
Get	GET	/rest/v1/agents?id=eq.{id}	Get single agent
Create	POST	/rest/v1/agents	Create new agent
Update	PATCH	/rest/v1/agents?id=eq.{id}	Update agent
Delete	DELETE	/rest/v1/agents?id=eq.{id}	Delete agent

List Agents

Retrieve all agents owned by the authenticated user.

Request

Using Supabase Client:

const { data: agents, error } = await supabase
  .from('agents')
  .select('*')
  .order('created_at', { ascending: false });

Using REST API:

curl -X GET \
  'https://your-project.supabase.co/rest/v1/agents?order=created_at.desc' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'apikey: YOUR_ANON_KEY'

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Research Assistant",
      "role": "Researcher",
      "avatar": "https://api.dicebear.com/7.x/bottts/svg?seed=research",
      "framework": "openai",
      "model": "gpt-4o",
      "system_prompt": "You are a helpful research assistant specializing in data analysis and literature review.",
      "settings": {
        "temperature": 0.7,
        "max_tokens": 4096,
        "presence_penalty": 0,
        "frequency_penalty": 0
      },
      "status": "idle",
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:00:00.000Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Code Reviewer",
      "role": "Developer",
      "avatar": "https://api.dicebear.com/7.x/bottts/svg?seed=coder",
      "framework": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "system_prompt": "You are an expert code reviewer...",
      "settings": {
        "temperature": 0.3,
        "max_tokens": 8192
      },
      "status": "idle",
      "created_at": "2024-01-14T15:30:00.000Z",
      "updated_at": "2024-01-15T09:00:00.000Z"
    }
  ],
  "error": null
}

Query Parameters

Parameter	Type	Description
select	string	Fields to return (default: *)
order	string	Sort order (e.g., created_at.desc)
limit	number	Max results to return
offset	number	Number of results to skip

Filter Examples

// Filter by framework
const { data } = await supabase
  .from('agents')
  .select('*')
  .eq('framework', 'openai');

// Filter by status
const { data } = await supabase
  .from('agents')
  .select('*')
  .eq('status', 'active');

// Search by name
const { data } = await supabase
  .from('agents')
  .select('*')
  .ilike('name', '%assistant%');

// Pagination
const { data } = await supabase
  .from('agents')
  .select('*')
  .range(0, 9); // First 10 results

Get Agent

Retrieve a single agent by ID.

Request

Using Supabase Client:

const { data: agent, error } = await supabase
  .from('agents')
  .select('*')
  .eq('id', '550e8400-e29b-41d4-a716-446655440001')
  .maybeSingle();

Using REST API:

curl -X GET \
  'https://your-project.supabase.co/rest/v1/agents?id=eq.550e8400-e29b-41d4-a716-446655440001' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'apikey: YOUR_ANON_KEY' \
  -H 'Accept: application/vnd.pgrst.object+json'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Research Assistant",
    "role": "Researcher",
    "avatar": "https://api.dicebear.com/7.x/bottts/svg?seed=research",
    "framework": "openai",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful research assistant...",
    "settings": {
      "temperature": 0.7,
      "max_tokens": 4096
    },
    "status": "idle",
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-15T10:00:00.000Z"
  },
  "error": null
}

// Get agent with assigned tools
const { data: agent, error } = await supabase
  .from('agents')
  .select(`
    *,
    agent_tools (
      tool_id,
      enabled,
      configuration,
      tool:tools (
        id,
        name,
        description,
        category
      )
    )
  `)
  .eq('id', agentId)
  .maybeSingle();

Create Agent

Create a new AI agent.

Request

Using Supabase Client:

const { data: agent, error } = await supabase
  .from('agents')
  .insert({
    name: 'Data Analyst',
    role: 'Analyst',
    framework: 'openai',
    model: 'gpt-4o',
    system_prompt: `You are a data analyst expert. You help users:
- Analyze datasets and identify patterns
- Create visualizations and reports
- Provide statistical insights
- Recommend data-driven decisions

Always explain your methodology and cite sources.`,
    settings: {
      temperature: 0.5,
      max_tokens: 4096,
      presence_penalty: 0.1,
      frequency_penalty: 0.1
    }
  })
  .select()
  .single();

Using REST API:

curl -X POST \
  'https://your-project.supabase.co/rest/v1/agents' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'apikey: YOUR_ANON_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Prefer: return=representation' \
  -d '{
    "name": "Data Analyst",
    "role": "Analyst",
    "framework": "openai",
    "model": "gpt-4o",
    "system_prompt": "You are a data analyst expert...",
    "settings": {
      "temperature": 0.5,
      "max_tokens": 4096
    }
  }'

Request Body

Field	Type	Required	Description
name	string	Yes	Agent display name (1-100 chars)
role	string	No	Agent role/title
avatar	string	No	Avatar URL
framework	string	Yes	AI provider: openai, anthropic, google
model	string	No	Model ID (defaults to provider default)
system_prompt	string	No	System instructions for the agent
settings	object	No	Model configuration settings

Settings Object

Field	Type	Default	Description
temperature	number	0.7	Creativity (0-2)
max_tokens	number	4096	Max response length
presence_penalty	number	0	Topic diversity (-2 to 2)
frequency_penalty	number	0	Repetition penalty (-2 to 2)
top_p	number	1	Nucleus sampling
stop	string[]	null	Stop sequences

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Data Analyst",
    "role": "Analyst",
    "avatar": null,
    "framework": "openai",
    "model": "gpt-4o",
    "system_prompt": "You are a data analyst expert...",
    "settings": {
      "temperature": 0.5,
      "max_tokens": 4096,
      "presence_penalty": 0.1,
      "frequency_penalty": 0.1
    },
    "status": "idle",
    "created_at": "2024-01-15T12:00:00.000Z",
    "updated_at": "2024-01-15T12:00:00.000Z"
  },
  "error": null
}

Validation Errors

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "name": "Name is required",
      "framework": "Framework must be one of: openai, anthropic, google"
    }
  }
}

Update Agent

Update an existing agent's properties.

Request

Using Supabase Client:

const { data: agent, error } = await supabase
  .from('agents')
  .update({
    name: 'Senior Data Analyst',
    system_prompt: 'Updated instructions...',
    settings: {
      temperature: 0.6,
      max_tokens: 8192
    }
  })
  .eq('id', '550e8400-e29b-41d4-a716-446655440003')
  .select()
  .single();

Using REST API:

curl -X PATCH \
  'https://your-project.supabase.co/rest/v1/agents?id=eq.550e8400-e29b-41d4-a716-446655440003' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'apikey: YOUR_ANON_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Prefer: return=representation' \
  -d '{
    "name": "Senior Data Analyst",
    "settings": {"temperature": 0.6}
  }'

Partial Updates

Only include fields you want to change:

// Update only the model
const { error } = await supabase
  .from('agents')
  .update({ model: 'gpt-4-turbo' })
  .eq('id', agentId);

// Update only settings (merges with existing)
const { error } = await supabase
  .from('agents')
  .update({
    settings: { ...existingSettings, temperature: 0.8 }
  })
  .eq('id', agentId);

Delete Agent

Permanently delete an agent.

Request

Using Supabase Client:

const { error } = await supabase
  .from('agents')
  .delete()
  .eq('id', '550e8400-e29b-41d4-a716-446655440003');

Using REST API:

curl -X DELETE \
  'https://your-project.supabase.co/rest/v1/agents?id=eq.550e8400-e29b-41d4-a716-446655440003' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'apikey: YOUR_ANON_KEY'

Response

Success returns empty response with 204 status.

Cascade Behavior

Deleting an agent:

Removes agent from all swarms
Deletes agent tool assignments
Preserves messages (sender marked as deleted)

Agent Tools

Manage tool assignments for agents.

List Agent Tools

const { data: tools, error } = await supabase
  .from('agent_tools')
  .select(`
    id,
    agent_id,
    tool_id,
    enabled,
    configuration,
    created_at,
    tool:tools (
      id,
      name,
      description,
      category,
      icon,
      input_schema
    )
  `)
  .eq('agent_id', agentId);

Assign Tool to Agent

const { data, error } = await supabase
  .from('agent_tools')
  .insert({
    agent_id: agentId,
    tool_id: toolId,
    enabled: true,
    configuration: {
      api_key_ref: 'user_weather_api_key',
      default_units: 'metric'
    }
  })
  .select()
  .single();

Update Tool Configuration

const { error } = await supabase
  .from('agent_tools')
  .update({
    enabled: false,
    configuration: { ...newConfig }
  })
  .eq('agent_id', agentId)
  .eq('tool_id', toolId);

Remove Tool from Agent

const { error } = await supabase
  .from('agent_tools')
  .delete()
  .eq('agent_id', agentId)
  .eq('tool_id', toolId);

Agent Status

Track agent activity status.

Status Values

Status	Description
idle	Agent not currently active
thinking	Agent processing a request
responding	Agent generating response
error	Agent encountered an error

Update Status

const { error } = await supabase
  .from('agents')
  .update({ status: 'thinking' })
  .eq('id', agentId);

const channel = supabase
  .channel('agent-status')
  .on(
    'postgres_changes',
    {
      event: 'UPDATE',
      schema: 'public',
      table: 'agents',
      filter: `id=eq.${agentId}`
    },
    (payload) => {
      console.log('Agent status:', payload.new.status);
    }
  )
  .subscribe();

Error Codes

Code	Status	Description
AGENT_NOT_FOUND	404	Agent does not exist
AGENT_LIMIT_REACHED	403	Max agents limit reached
INVALID_FRAMEWORK	400	Unknown AI provider
INVALID_MODEL	400	Model not available for framework
PERMISSION_DENIED	403	Cannot access this agent

[Swarms API](/docs/api/swarms-api): Assign agents to swarms
[Messages API](/docs/api/messages-api): Agent responses
[Tools API](/docs/api/tools-api): Tool management

Agents API

Agents API

Database Schema

Endpoints Overview

List Agents

Request

Response

Query Parameters

Filter Examples

Get Agent

Request

Response

Get Agent with Related Data

Create Agent

Request

Request Body

Settings Object

Response

Validation Errors

Update Agent

Request

Partial Updates

Delete Agent

Request

Response

Cascade Behavior

Agent Tools

List Agent Tools

Assign Tool to Agent

Update Tool Configuration

Remove Tool from Agent

Agent Status

Status Values

Update Status

Subscribe to Status Changes

Error Codes

Related Endpoints

Cookie Preferences