Agents API

Manage AI agents that handle phone conversations with patients. Agents contain the configuration, personality, and knowledge base for conducting calls.

List Agents

Get all available agents for your organization.

GET /api/v1/agents

Purpose

Retrieve a list of all AI agents configured for your organization. Returns only the agent IDs and titles for quick reference.

Response

{
  "data": [
    {
      "id": "uuid",
      "title": "Appointment Reminder Agent"
    },
    {
      "id": "uuid", 
      "title": "Post-Visit Follow-up Agent"
    }
  ],
  "count": 2
}

Example

curl -X GET https://orchestrator.helloblair.com/api/v1/agents \
  -H "X-API-Key: YOUR_API_KEY"

Get Agent Details

Retrieve detailed information about a specific agent.

GET /api/v1/agents/{agentId}

Purpose

Get comprehensive details about a specific AI agent including its description and knowledge base.

Path Parameters

Parameter	Type	Description
agentId	uuid	The unique identifier of the agent

Response

{
  "id": "uuid",
  "title": "Appointment Reminder Agent",
  "description": "Agent for handling appointment reminders and confirmations",  // nullable
  "knowledge_base": "You are a helpful medical assistant..."  // nullable
}

Fields

• id: Unique identifier for the agent
• title: Display name of the agent
• description: Brief description of the agent's purpose (nullable)
• knowledge_base: The agent's prompt and instructions (nullable)

Error Responses

• 404 Not Found: "Agent not found" - Agent doesn't exist or you don't have access

Example

curl -X GET https://orchestrator.helloblair.com/api/v1/agents/YOUR_AGENT_ID \
  -H "X-API-Key: YOUR_API_KEY"

Update Agent

Modify an existing agent's configuration.

PATCH /api/v1/agents/{agentId}

Purpose

Update the knowledge base of an AI agent. Currently only supports updating the knowledge_base field.

Path Parameters

Parameter	Type	Description
agentId	uuid	The unique identifier of the agent

Request Body

{
  "knowledge_base": "Updated instructions and prompts"  // Optional, max 20000 characters
}

Response

Success response when knowledge base is updated:

{
  "id": "22222222-2222-2222-2222-222222222222",
  "title": "Appointment Reminder Agent",
  "description": "Agent for handling appointment reminders and confirmations",  // nullable
  "knowledge_base": "Updated instructions and prompts",  // nullable
  "message": "Agent updated successfully"
}

Response when knowledge_base is not provided:

{
  "id": "22222222-2222-2222-2222-222222222222",
  "title": "Appointment Reminder Agent",
  "description": "Agent for handling appointment reminders and confirmations",  // nullable
  "knowledge_base": "Previous knowledge base content",  // nullable
  "message": "Missing knowledge base skipped updating"
}

Notes

• Currently only knowledge_base field can be updated
• The knowledge base is also stored in Pinecone vector database for retrieval
• Maximum knowledge_base length is 20,000 characters
• You can only update agents in your organization

Error Responses

• 404 Not Found: "Agent not found" - Agent doesn't exist or you don't have access
• 500 Internal Server Error: "Failed to update agent" - Server error

Example

curl -X PATCH https://orchestrator.helloblair.com/api/v1/agents/YOUR_AGENT_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_base": "You are a helpful medical assistant. Your role is to confirm appointments and answer basic questions."
  }'

Clear Agent Knowledge Base

Remove the knowledge base from an agent.

DELETE /api/v1/agents/{agentId}

Purpose

Clear the knowledge base content from an agent and remove it from the Pinecone vector database. This does not delete the agent itself.

Path Parameters

Parameter	Type	Description
agentId	uuid	The unique identifier of the agent

Response

{
  "message": "Knowledge base deleted successfully",
  "id": "22222222-2222-2222-2222-222222222222",
  "title": "Appointment Reminder Agent",
  "description": "Agent for handling appointment reminders and confirmations",  // nullable
  "knowledge_base": null  // Set to null after deletion
}

Notes

• This operation clears the knowledge_base field and removes vectors from Pinecone
• The agent itself remains available and can still be used
• You can restore the knowledge base using the PATCH endpoint
• You can only delete knowledge bases from agents in your organization

Error Responses

• 404 Not Found: "Agent not found" - Agent doesn't exist or you don't have access
• 500 Internal Server Error: "Failed to delete knowledge base" - Server error

Example

curl -X DELETE https://orchestrator.helloblair.com/api/v1/agents/YOUR_AGENT_ID \
  -H "X-API-Key: YOUR_API_KEY"

Agent Configuration

Knowledge Base Format

The knowledge_base field contains the agent's system prompt and instructions. It should be structured to guide the agent's behavior during calls:

You are a helpful medical assistant for [Practice Name].

Your responsibilities:
1. Confirm patient appointments
2. Answer basic questions about visit preparation
3. Collect necessary pre-visit information

Guidelines:
- Be professional and empathetic
- Keep conversations concise
- Escalate complex medical questions to staff

Using Agents in Calls

When creating calls, specify the agentId to determine which agent configuration to use:

{
  "patients": [{"patientId": "22222222-2222-2222-2222-222222222222"}],
  "agentId": "22222222-2222-2222-2222-222222222222",  // Specifies which agent to use
  "recording": true
}

Best Practices

1. Keep knowledge bases concise but comprehensive (max 20,000 characters)
2. Version your knowledge bases externally for rollback capabilities
3. Update knowledge bases based on real call outcomes and any outdated information
4. Keep knowledge base sectioned and organized Make sure your knowledge base is well organized and sectioned off based on topic. This will improve the agent's ability to find relevant information quickly

Important Notes

• API responses return timestamps in ISO 8601 format with UTC timezone (e.g., 2024-01-15T10:00:00.000Z)
• API requests accept ISO 8601 timestamps with any timezone offset (e.g., 2024-01-15T10:00:00.000Z, 2024-01-15T10:00:00.000+00:00, 2024-01-15T10:00:00.000-05:00)
• The DELETE endpoint only clears the knowledge_base field, it does not delete the agent itself
• Knowledge base updates are immediately reflected