Get Agent

Fetches a single agent from the Ultravox API by ID and combines it with the local agent_mappings record, call statistics, and assigned phone numbers. Returns a comprehensive detail view suitable for an agent detail page.

Endpoint

Property	Value
Function Name	agents-get
HTTP Method	GET
Authentication	Supabase JWT (Bearer token)
Required Role	Any agency user (no specific role required beyond agency membership)

Request

Headers

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Query Parameters

Field	Type	Required	Description
agent_id	string	Yes	The Ultravox agent ID to retrieve.

Response

Success (200)

{
  "ultravox_agent": {
    "id": "uv-agent-abc123",
    "name": "My_Agent",
    "system_prompt": "You are a helpful assistant...",
    "model": "fixie-ai/ultravox-70B",
    "voice": "terrence",
    "temperature": 0.4,
    "created_at": "2025-01-15T10:30:00Z"
  },
  "mapping": {
    "id": "uuid-of-mapping",
    "ultravox_agent_id": "uv-agent-abc123",
    "ultravox_agent_name": "My_Agent",
    "client_id": "uuid-of-client",
    "client_name": "Acme Corp",
    "campaign_id": "uuid-of-campaign",
    "campaign_name": "Q1 Outreach",
    "campaign_type": "outbound",
    "default_direction": "outbound",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "stats": {
    "total_calls": 150,
    "avg_duration": 245,
    "successful_calls": 120
  },
  "phone_numbers": [
    {
      "phone_number": "+15551234567",
      "created_at": "2025-01-20T08:00:00Z"
    }
  ]
}

The mapping field is null if no local mapping exists for the agent. The phone_numbers array is empty if no phone numbers are assigned or if there is no local mapping.

Error Responses

Status	Condition
400	agent_id query parameter is missing
400	Ultravox API key is not configured for the agency
401	Missing or invalid authorization header
403	User is not associated with an agency
404	Agent not found in Ultravox
405	HTTP method is not GET
500	Unexpected server error
502	Ultravox API returned a non-404 error

Behavior

• Authenticates the user via Supabase JWT and verifies they belong to an agency.
• Validates the required agent_id query parameter.
• Retrieves the agency's Ultravox API key by calling the get_agency_credentials RPC function.
• Sends a GET request to https://api.ultravox.ai/api/agents/{agent_id} to fetch the full agent details including the call template.
• Fetches the local agent_mappings record for this agent (scoped to the user's agency), including joined clients and campaigns data.
• Queries the calls table to compute call statistics for this agent within the agency: total calls, number of completed (successful) calls, and average duration in seconds (rounded to nearest integer).
• If a local mapping exists, queries the agency_phone_numbers table for active phone numbers assigned to the mapping.
• Returns the combined response matching the frontend AgentGetResponse type.

Database Tables

Table	Operation	Description
users	Read	Fetches user profile to determine agency_id
agent_mappings	Read	Fetches local mapping for the agent, with joined clients and campaigns
calls	Read	Fetches all calls for this agent/agency to compute statistics
agency_phone_numbers	Read	Fetches active phone numbers assigned to the agent mapping

External APIs

API	Method	Endpoint	Description
Ultravox	GET	/api/agents/{agent_id}	Fetches full agent details

Related Functions

• List Agents -- List all agents with merged data
• Update Agent -- Update the agent's configuration
• Delete Agent -- Delete the agent
• Assign Agent -- Assign the agent to a client or campaign