Skip to main content

Managing Agents

List, update, and maintain your agent configurations.

List Agents​

View all your configured agents.

Via Web Interface​

  1. Navigate to Agents in the sidebar
  2. View all agents with:
    • Name and type
    • Model used
    • Tools configured
    • Creation date
    • Last activity

Via API​

import requests

response = requests.get(
    "http://localhost/api/v1/agent/configs",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"}
)

agents = response.json()["configs"]
for agent in agents:
    print(f"ID: {agent['id']}")
    print(f"Name: {agent['name']}")
    print(f"Display Name: {agent.get('display_name', 'N/A')}")
    print(f"Model: {agent['model']}")
    print(f"Tools: {agent.get('builtin_tools', [])}")
    print(f"Created: {agent['created_at']}")
    print("-" * 40)

Get Agent Details​

Retrieve full configuration for a specific agent.

import requests

agent_id = "your-agent-id"

response = requests.get(
    f"http://localhost/api/v1/agent/configs/{agent_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"}
)

agent = response.json()
print(f"Name: {agent['name']}")
print(f"System Prompt: {agent['system_prompt']}")
print(f"Temperature: {agent['temperature']}")
print(f"Max Iterations: {agent['max_iterations']}")

Update Agents​

Modify existing agent configurations.

Update Personality​

response = requests.put(
    f"http://localhost/api/v1/agent/configs/{agent_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    json={
        "system_prompt": "You are now a senior research assistant. Provide more detailed and technical answers.",
        "temperature": 0.2  # Lower temperature for more focused responses
        "fallback_responses": [
            "Let me research that further.",
            "Would you like me to consult the technical documentation?"
        ]
    }
)

print(f"Updated agent: {response.json()['name']}")

Update Tools​

response = requests.put(
    f"http://localhost/api/v1/agent/configs/{agent_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    json={
        "builtin_tools": ["rag_search", "web_search", "code_execution"],
        "tool_choice": "auto"
    }
)

Update Model​

response = requests.put(
    f"http://localhost/api/v1/agent/configs/{agent_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    json={
        "model": "gpt-4"  # Upgrade model
    }
)

Update Tool Choice Strategy​

response = requests.put(
    f"http://localhost/api/v1/agent/configs/{agent_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    json={
        "tool_choice": "required"  # Force tool usage
    }
)

Update Max Iterations​

response = requests.put(
    f"http://localhost/api/v1/agent/configs/{agent_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    json={
        "max_iterations": 10  # Allow more tool iterations
    }
)

Update Tool Resources​

response = requests.put(
    f"http://localhost/api/v1/agent/configs/{agent_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    json={
        "tool_resources": {
            "code_execution": {
                "timeout": 60,
                "allowed_libraries": ["pandas", "numpy", "scikit-learn"]
            }
        }
    }
)

Clone Agents​

Create a new agent based on an existing one.

import requests

original_id = "original-agent-id"

# Get original agent
get_response = requests.get(
    f"http://localhost/api/v1/agent/configs/{original_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"}
)

original = get_response.json()

# Create new agent with same config
create_response = requests.post(
    "http://localhost/api/v1/agent/configs",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    json={
        "name": f"{original['name']} - Copy",
        "system_prompt": original["system_prompt"],
        "model": original["model"],
        "builtin_tools": original["builtin_tools"],
        "mcp_servers": original.get("mcp_servers", [])
    }
)

new_agent = create_response.json()
print(f"Created copy: {new_agent['id']}")

Delete Agents​

Remove agents you no longer need.

Via Web Interface​

  1. Navigate to Agents
  2. Find the agent to delete
  3. Click Delete
  4. Confirm deletion

Via API​

import requests

agent_id = "your-agent-id"

response = requests.delete(
    f"http://localhost/api/v1/agent/configs/{agent_id}",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"}
)

if response.status_code == 204:
    print("Agent deleted successfully")
else:
    print(f"Error: {response.status_code}")

Monitoring Agent Performance​

Track how well your agents are performing.

Check Agent Stats​

import requests

agent_id = "your-agent-id"

response = requests.get(
    f"http://localhost/api/v1/analytics/agent-performance",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    params={
        "agent_id": agent_id,
        "period": "7d"
    }
)

stats = response.json()
print(f"Success Rate: {stats['success_rate']:.2%}")
print(f"Average Response Time: {stats['avg_response_time']}ms")
print(f"RAG Hit Rate: {stats['rag_hit_rate']:.2%}")
print(f"Average Tool Usage: {stats['avg_tools_per_request']:.1f}")

Tool Usage Analysis​

response = requests.get(
    f"http://localhost/api/v1/analytics/tool-usage",
    headers={"Authorization": "Bearer YOUR_JWT_TOKEN"},
    params={
        "agent_id": agent_id,
        "period": "30d"
    }
)

stats = response.json()
for tool in stats["tool_breakdown"]:
    print(f"{tool['tool_name']}:")
    print(f"  Usage Count: {tool['usage_count']}")
    print(f"  Success Rate: {tool['success_rate']:.2%}")
    print(f"  Avg Response Time: {tool['avg_response_time']}ms")

Best Practices​

Organization​

  1. Use Descriptive Names - Make agents easy to identify
  2. Categorize Agents - Group by purpose (research, support, analysis)
  3. Document Changes - Keep track of configuration updates
  4. Version Agents - Include version in names when updating

Lifecycle Management​

StageAction
DevelopmentCreate and test extensively
TestingDeploy to staging environment
ProductionMonitor and optimize
DeprecationMark as deprecated, plan migration

Security​

  1. Separate Permissions - Use dedicated API keys for different agents
  2. Monitor Tool Access - Be aware of which agents have tool permissions
  3. Review MCP Servers - Regularly audit custom tool connections
  4. Audit Usage - Monitor agent performance and costs

Troubleshooting​

Agent Not Responding​

Problem: Agent returns errors or doesn't generate output

Check:

  • Agent is enabled
  • Model is available
  • System prompt is not too restrictive
  • Tool configurations are correct

Poor Tool Selection​

Problem: Agent doesn't use available tools

Solution:

  • Adjust tool_choice to auto or required
  • Verify tools are in builtin_tools list
  • Check MCP server connections
  • Review system prompt to encourage tool use

Exceeding Iterations​

Problem: Agent hits max iterations without completing task

Solution:

  • Increase max_iterations in configuration
  • Simplify the task or prompt
  • Improve tool selection and efficiency
  • Break complex tasks into smaller steps

Next Steps​