Agents API - Vijil

The Agents API allows you to register agents with Vijil, manage their configurations, and associate them with evaluations and Dome guardrails.

Actions

Action	Description
ListAgents	List all registered agents
CreateAgent	Register a new agent
GetAgent	Get details for a specific agent
UpdateAgent	Update an agent’s configuration
DeleteAgent	Delete a registered agent

ListAgents

Returns a list of all agents registered to your account.

Request Syntax

GET /v1/agents HTTP/1.1
Authorization: Bearer {api_key}

Query Parameters

Parameter	Type	Required	Description
include_archived	Boolean	No	Include archived agents. Default: `false`.

Response Syntax

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "hub": "string",
      "model_name": "string",
      "status": "string",
      "trust_score": number,
      "created_at": "string"
    }
  ]
}

Response Elements

Element	Type	Description
data	Array	List of agent objects.
data[].id	String	Unique agent identifier. Format: `agent-{uuid}`.
data[].name	String	Agent display name.
data[].hub	String	Model provider. See Supported Hubs.
data[].model_name	String	Model identifier at the provider.
data[].status	String	Agent status: `active` or `archived`.
data[].trust_score	Number	Latest Trust Score (0.0–1.0). Null if not evaluated.
data[].created_at	String	ISO 8601 timestamp of creation.

Example

Request:

curl -X GET "https://api.vijil.ai/v1/agents" \
  -H "Authorization: Bearer $VIJIL_API_KEY"

Response:

{
  "data": [
    {
      "id": "agent-abc123",
      "name": "Customer Support Bot",
      "hub": "openai",
      "model_name": "gpt-4o",
      "status": "active",
      "trust_score": 0.85,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Python:

agents = vijil.agents.list(include_archived=False)

CreateAgent

Registers a new agent with Vijil. The agent can then be evaluated and protected with Dome guardrails.

Request Syntax

POST /v1/agents HTTP/1.1
Content-Type: application/json
Authorization: Bearer {api_key}

{
  "agent_name": "string",
  "hub": "string",
  "model_name": "string",
  "api_key_value": "string",
  "api_key_name": "string",
  "agent_system_prompt": "string",
  "model_url": "string",
  "hub_config": {}
}

Request Parameters

Parameter	Type	Required	Description
agent_name	String	Yes	Display name for the agent. Must be unique within your account.
hub	String	Yes	Model provider. See Supported Hubs.
model_name	String	Yes	Model identifier (e.g., `gpt-4o`, `claude-3-sonnet`).
api_key_value	String	Conditional	API key for the model provider. Required if `api_key_name` not provided.
api_key_name	String	Conditional	Name of a stored API key. Required if `api_key_value` not provided.
agent_system_prompt	String	No	System prompt to use when evaluating the agent.
model_url	String	Conditional	Endpoint URL for `custom` hub. Required if `hub` is `custom`.
hub_config	Object	Conditional	Provider-specific configuration. Required for `bedrock` and `vertex`. See Hub Configuration.

Hub Configuration

For AWS Bedrock:

{
  "region": "us-east-1",
  "access_key": "AKIA...",
  "secret_access_key": "..."
}

For Google Vertex AI:

{
  "project_id": "my-project",
  "location": "us-central1",
  "service_account_json": "..."
}

Response Syntax

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "string",
  "name": "string",
  "hub": "string",
  "model_name": "string",
  "status": "string",
  "created_at": "string"
}

Response Elements

Element	Type	Description
id	String	Unique agent identifier. Format: `agent-{uuid}`.
name	String	Agent display name.
hub	String	Model provider.
model_name	String	Model identifier.
status	String	Initial status. Always `active` for new agents.
created_at	String	ISO 8601 timestamp of creation.

Errors

Error	HTTP Status	Description
`InvalidRequestException`	400	Request body is malformed or missing required fields.
`InvalidApiKeyException`	401	Vijil API key is invalid or expired.
`AgentAlreadyExistsException`	409	An agent with this name already exists.
`InvalidHubException`	400	The specified hub is not supported.

Example

Request:

curl -X POST "https://api.vijil.ai/v1/agents" \
  -H "Authorization: Bearer $VIJIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Customer Support Bot",
    "hub": "openai",
    "model_name": "gpt-4o",
    "api_key_value": "sk-...",
    "agent_system_prompt": "You are a helpful customer support agent."
  }'

Response:

{
  "id": "agent-abc123",
  "name": "Customer Support Bot",
  "hub": "openai",
  "model_name": "gpt-4o",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Python:

agent = vijil.agents.create(
    agent_name="Customer Support Bot",
    hub="openai",
    model_name="gpt-4o",
    api_key_value="sk-...",
    agent_system_prompt="You are a helpful customer support agent."
)

GetAgent

Retrieves details for a specific agent.

Request Syntax

GET /v1/agents/{agent_name} HTTP/1.1
Authorization: Bearer {api_key}

URI Parameters

Parameter	Type	Required	Description
agent_name	String	Yes	The agent’s display name.

Response Syntax

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "string",
  "name": "string",
  "hub": "string",
  "model_name": "string",
  "status": "string",
  "trust_score": number,
  "agent_system_prompt": "string",
  "created_at": "string",
  "updated_at": "string"
}

Response Elements

Element	Type	Description
id	String	Unique agent identifier.
name	String	Agent display name.
hub	String	Model provider.
model_name	String	Model identifier.
status	String	Agent status: `active` or `archived`.
trust_score	Number	Latest Trust Score (0.0–1.0). Null if not evaluated.
agent_system_prompt	String	System prompt. Null if not set.
created_at	String	ISO 8601 timestamp of creation.
updated_at	String	ISO 8601 timestamp of last update.

Errors

Error	HTTP Status	Description
`AgentNotFoundException`	404	Agent does not exist.

Example

Request:

curl -X GET "https://api.vijil.ai/v1/agents/Customer%20Support%20Bot" \
  -H "Authorization: Bearer $VIJIL_API_KEY"

Python:

agent = vijil.agents.get(agent_name="Customer Support Bot")

UpdateAgent

Updates an existing agent’s configuration.

Request Syntax

PATCH /v1/agents/{agent_name} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {api_key}

{
  "new_agent_name": "string",
  "agent_system_prompt": "string",
  "api_key_value": "string",
  "api_key_name": "string"
}

URI Parameters

Parameter	Type	Required	Description
agent_name	String	Yes	Current agent name.

Request Parameters

Parameter	Type	Required	Description
new_agent_name	String	No	New display name for the agent.
agent_system_prompt	String	No	Updated system prompt.
api_key_value	String	No	New API key for the model provider.
api_key_name	String	No	Name of a stored API key to use.

Response Syntax

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "string",
  "name": "string",
  "status": "string",
  "updated_at": "string"
}

Errors

Error	HTTP Status	Description
`AgentNotFoundException`	404	Agent does not exist.
`AgentAlreadyExistsException`	409	An agent with the new name already exists.

Example

Request:

curl -X PATCH "https://api.vijil.ai/v1/agents/Customer%20Support%20Bot" \
  -H "Authorization: Bearer $VIJIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "new_agent_name": "Support Bot v2",
    "agent_system_prompt": "You are a helpful and concise support agent."
  }'

Python:

vijil.agents.update(
    agent_name="Customer Support Bot",
    new_agent_name="Support Bot v2",
    agent_system_prompt="You are a helpful and concise support agent."
)

DeleteAgent

Permanently deletes an agent and disassociates it from any evaluations.

Request Syntax

DELETE /v1/agents/{agent_name} HTTP/1.1
Authorization: Bearer {api_key}

URI Parameters

Parameter	Type	Required	Description
agent_name	String	Yes	The agent’s display name.

Response Syntax

HTTP/1.1 204 No Content

Errors

Error	HTTP Status	Description
`AgentNotFoundException`	404	Agent does not exist.

Example

Request:

curl -X DELETE "https://api.vijil.ai/v1/agents/Customer%20Support%20Bot" \
  -H "Authorization: Bearer $VIJIL_API_KEY"

Python:

vijil.agents.delete(agent_name="Customer Support Bot")

Supported Hubs

Hub	Description
`openai`	OpenAI GPT models (GPT-4, GPT-4o, etc.)
`anthropic`	Anthropic Claude models
`bedrock`	AWS Bedrock foundation models
`bedrockAgents`	AWS Bedrock Agents
`vertex`	Google Vertex AI
`digitalocean`	DigitalOcean GenAI
`custom`	Any OpenAI-compatible endpoint

Get Started

Use Frameworks

Evaluate Agents

Protect Agents

Deploy with CI/CD

Deploy On-Premises

API Reference

​Actions

​ListAgents

​Request Syntax

​Query Parameters

​Response Syntax

​Response Elements

​Example

​CreateAgent

​Request Syntax

​Request Parameters

​Hub Configuration

​Response Syntax

​Response Elements

​Errors

​Example

​GetAgent

​Request Syntax

​URI Parameters

​Response Syntax

​Response Elements

​Errors

​Example

​UpdateAgent

​Request Syntax

​URI Parameters

​Request Parameters

​Response Syntax

​Errors

​Example

​DeleteAgent

​Request Syntax

​URI Parameters

​Response Syntax

​Errors

​Example

​Supported Hubs

​See Also

Actions

ListAgents

Request Syntax

Query Parameters

Response Syntax

Response Elements

Example

CreateAgent

Request Syntax

Request Parameters

Hub Configuration

Response Syntax

Response Elements

Errors

Example

GetAgent

Request Syntax

URI Parameters

Response Syntax

Response Elements

Errors

Example

UpdateAgent

Request Syntax

URI Parameters

Request Parameters

Response Syntax

Errors

Example

DeleteAgent

Request Syntax

URI Parameters

Response Syntax

Errors

Example

Supported Hubs

See Also