Agent Audit API
Audit agent configurations, test capabilities, migrate between agent types, and validate marketplace readiness.
Base URL: https://api.vell.ai/api/v1
Authentication: Bearer token
Prefix: /agents/audit
Dashboard & Overview
List All Agents
Returns all agents with summary statistics, type comparisons, and migration recommendations.
Response:
{
"agents": [
{
"id": 1,
"name": "Content Writer",
"type": "internal",
"type_label": "Internal",
"memory_enabled": false,
"bedrock_agent_id": null,
"executions_count": 45,
"capabilities_count": 8,
"guardrail_enabled": true,
"is_active": true,
"marketplace_status": null
}
],
"summary": {
"total_agents": 5,
"internal_agents": 3,
"bedrock_memory_agents": 2,
"with_memory": 2,
"with_guardrails": 4,
"active": 5
},
"type_comparison": {},
"migration_recommendations": {},
"available_types": [
{
"value": "internal",
"label": "Internal",
"description": "Standard agent with local execution",
"requires_bedrock": false,
"supports_dry_run": true
}
]
}
Company Analytics
GET /agents/audit/company-analytics
| Parameter |
Type |
Required |
Default |
Description |
period |
string |
No |
30d |
Time period for analytics |
Marketplace Metrics
GET /agents/audit/marketplace-metrics
| Parameter |
Type |
Required |
Default |
Description |
period |
string |
No |
30d |
Time period |
Per-Agent Operations
All per-agent endpoints require the agent to be owned by (or shared with) the authenticated user's company or team.
Agent Metrics
GET /agents/audit/{agent}/metrics
| Parameter |
Type |
Location |
Default |
Description |
agent |
integer |
path |
— |
Agent ID |
period |
string |
query |
30d |
Time period |
Validate Configuration
GET /agents/audit/{agent}/validate
Returns Bedrock validation, dry-run validation, configuration analysis, and marketplace requirements.
Migrate Agent
POST /agents/audit/{agent}/migrate
| Parameter |
Type |
Required |
Description |
target_type |
string |
Yes |
internal, bedrock_memory, or bedrock_full |
dry_run |
boolean |
No |
Preview changes without applying (default: false) |
options |
object |
No |
Migration-specific options |
Response (success):
{
"success": true,
"message": "Agent migrated to bedrock_memory",
"result": {}
}
Response (failure — 422):
{
"success": false,
"error": "Migration failed: agent has active executions"
}
Rollback Migration
POST /agents/audit/{agent}/rollback
| Parameter |
Type |
Required |
Description |
previous_config |
object |
Yes |
Previous configuration to restore |
Batch Migrate
POST /agents/audit/batch-migrate
| Parameter |
Type |
Required |
Description |
target_type |
string |
Yes |
internal or bedrock_memory |
agent_ids |
array |
Yes |
Agent IDs to migrate |
dry_run |
boolean |
No |
Preview mode (default: false) |
Dry Run & Testing
Execute Dry Run
POST /agents/audit/{agent}/dry-run
| Parameter |
Type |
Required |
Default |
Description |
task |
string |
Yes |
— |
Task description (max 1000 chars) |
context |
object |
No |
[] |
Additional context |
quality |
string |
No |
standard |
quick, standard, or deep |
generate_outputs |
boolean |
No |
false |
Generate sample outputs |
Challenge Workflow
POST /agents/audit/{agent}/challenge
| Parameter |
Type |
Required |
Default |
Description |
task |
string |
Yes |
— |
Task to challenge (max 1000 chars) |
dry_run_result |
object |
Yes |
— |
Previous dry-run result to challenge |
personas |
array |
No |
— |
Personas for multi-perspective evaluation |
quality |
string |
No |
standard |
quick, standard, or deep |
Marketplace Readiness
GET /agents/audit/{agent}/marketplace-readiness
| Parameter |
Type |
Required |
Default |
Description |
task |
string |
No |
General capability test |
Task for readiness evaluation |
Preview Capability
POST /agents/audit/{agent}/preview-capability
| Parameter |
Type |
Required |
Default |
Description |
capability |
string |
Yes |
— |
Capability slug |
parameters |
object |
No |
[] |
Capability parameters |
quality |
string |
No |
standard |
quick, standard, or deep |
Create Dry-Run Session
POST /agents/audit/{agent}/dry-run-session
| Parameter |
Type |
Required |
Default |
Description |
persona |
string |
No |
technical_reviewer |
Session persona |
quality |
string |
No |
standard |
Quality level |
context |
object |
No |
[] |
Additional context |
Response:
{
"session_id": 42,
"session_token": "drs_abc123def456",
"expires_at": "2026-02-26T12:00:00Z"
}
Use the returned session_token with the Dry-Run Sessions API for multi-turn conversations.
Capabilities
List Capabilities
GET /agents/audit/capabilities
| Parameter |
Type |
Required |
Default |
Description |
tier |
string |
No |
standard |
economy, standard, or premium |
Test Capability
POST /agents/audit/capabilities/{capability}/test
| Parameter |
Type |
Required |
Default |
Description |
capability |
string |
path |
— |
Capability slug |
parameters |
object |
No |
[] |
Test parameters |
context |
object |
No |
[] |
Additional context |
dry_run |
boolean |
No |
true |
Dry-run mode |
tier |
string |
No |
standard |
Model tier |
Estimate Cost
POST /agents/audit/capabilities/estimate-cost
| Parameter |
Type |
Required |
Description |
capabilities |
array |
Yes |
List of capability slugs |
tier |
string |
No |
economy, standard, or premium |
Get Model Recommendation
POST /agents/audit/capabilities/model-recommendation
| Parameter |
Type |
Required |
Description |
use_case |
string |
Yes |
cost_optimized, balanced, quality_focused, or research_heavy |
Set Capability Model Overrides
POST /agents/audit/{agent}/capability-models
| Parameter |
Type |
Required |
Description |
overrides |
object |
Yes |
Map of capability slug to model name |
Recommend Configuration
POST /agents/audit/recommend-configuration
| Parameter |
Type |
Required |
Description |
use_case |
string |
Yes |
Description of intended use case |
Use Cases
Evaluate Agent Before Migration
- Validate current config:
GET /agents/audit/{agent}/validate
- Preview the migration:
POST /agents/audit/{agent}/migrate with dry_run: true
- Run a dry-run test:
POST /agents/audit/{agent}/dry-run
- If satisfied, migrate:
POST /agents/audit/{agent}/migrate with dry_run: false
Optimize Costs Across Agents
- Get company analytics:
GET /agents/audit/company-analytics
- List capabilities with cost estimates:
POST /agents/audit/capabilities/estimate-cost
- Get model recommendation:
POST /agents/audit/capabilities/model-recommendation with use_case: "cost_optimized"
- Apply model overrides:
POST /agents/audit/{agent}/capability-models
Prepare Agent for Marketplace
- Check readiness:
GET /agents/audit/{agent}/marketplace-readiness
- Address any failing requirements
- Create a dry-run session for interactive testing:
POST /agents/audit/{agent}/dry-run-session
- Send test messages via Dry-Run Sessions API