Agents

Create, manage, and run AI agents with the AIP SDK.

🚀 Quick Start

from glaip_sdk import Client

client = Client()

# Create agent
agent = client.create_agent(
    name="math-tutor",
    instruction="You are a patient math tutor. Explain concepts clearly."
)

# Run agent
response = agent.run("What is 2 + 2?")
print(response)

# Clean up
agent.delete()

✅ Verify

Check that your agent was created successfully:

# List agents to verify creation
agents = client.list_agents()
math_tutors = [a for a in agents if "math" in a.name.lower()]
print(f"Found {len(math_tutors)} math tutor agents")

🧹 Clean Up

Always clean up resources when testing:

# Delete the agent
agent.delete()

# Or delete by ID if you don't have the object
client.delete_agent("agent-id")

🤖 Create Agents

Basic Agent Creation

# Create agent with basic configuration
agent = client.create_agent(
    name="assistant",
    instruction="You are a helpful AI assistant."
)

Agent with Tools

Tools Input: Use tool names or IDs. Multiple tools can be specified as --tools tool1,tool2 or --tools tool1 --tools tool2.

# Create tool from local file first
tool = client.create_tool(
    name="calculator-tool",
    file_path="calculator.py"
)

# Create agent with tool
agent = client.create_agent(
    name="math-agent",
    instruction="You are a math tutor. Use the calculator tool for calculations.",
    tools=[tool]
)

Tool Requirements: All tools must contain actual Python code with the @tool_plugin decorator and inherit from BaseTool. The CLI supports file uploads via --file option.

Agent with Other Agents

# Create specialist agents
researcher = client.create_agent(
    name="researcher",
    instruction="You research topics thoroughly and provide detailed information."
)

writer = client.create_agent(
    name="writer",
    instruction="You write clear, engaging content based on research."
)

# Create coordinator agent
coordinator = client.create_agent(
    name="coordinator",
    instruction="You coordinate between researchers and writers to create content.",
    agents=[researcher, writer]
)

📋 List and Find Agents

List All Agents

# Get all agents
agents = client.list_agents()

# Print agent details
for agent in agents:
    print(f"{agent.name}: {agent.description or 'No description'}")
    print(f"  ID: {agent.id}")
    print(f"  Model: {agent.model or 'Default'}")
    print(f"  Tools: {len(agent.tools or [])}")
    print()

Find Agents by Name

# Search for agents by name
math_agents = client.find_agents("math")
tutor_agents = client.find_agents("tutor")

print(f"Found {len(math_agents)} math agents")
print(f"Found {len(tutor_agents)} tutor agents")

🔍 Get Agent Details

# Get agent by ID
agent = client.get_agent_by_id("agent-123")

# Access agent properties
print(f"Name: {agent.name}")
print(f"Instruction: {agent.instruction}")

# Defensive property access for model and tools
cfg = getattr(agent, "agent_config", {}) or {}
print(f"Model: {cfg.get('lm_name') or getattr(agent, 'model', 'Default')}")
print(f"Tools: {len(getattr(agent, 'tools', []) or [])}")
print(f"Timeout: {getattr(agent, 'timeout', 'Default')}s")

🏃‍♂️ Run Agents

Basic Agent Run

# Run agent directly
response = client.run_agent("agent-id", "What is 2 + 2?")

# Or use the agent object
agent = client.get_agent_by_id("agent-id")
response = agent.run("What is 2 + 2?")

# With custom timeout
response = agent.run("Complex calculation", timeout=900)

Run with Files

# Run with file upload
with open("document.pdf", "rb") as f:
    response = agent.run("Summarize this", files=[f])

For more patterns (multiple files, IO objects, limits), see File Uploads.

✏️ Update Agents

Update Agent Properties

# Update single field
updated_agent = client.update_agent(
    "agent-id",
    instruction="Updated instruction text"
)

# Update multiple fields
updated_agent = client.update_agent(
    "agent-id",
    name="new-name",
    instruction="New instruction",
    timeout=600
)

# Or use the agent object
agent = client.get_agent_by_id("agent-id")
agent.update(
    instruction="Updated instruction",
    timeout=600
)

Update Agent Tools

# Add new tool
new_tool = client.create_tool(
    name="new-tool",
    description="New functionality",
    framework="langchain"
)

# Update agent with new tool
client.update_agent(
    "agent-id",
    tools=["existing-tool-id", new_tool.id]
)

# Remove all tools
client.update_agent("agent-id", tools=[])

🗑️ Delete Agents

# Delete by ID
client.delete_agent("agent-id")

# Or use the agent object
agent = client.get_agent_by_id("agent-id")
agent.delete()

# Delete multiple agents
agent_ids = ["agent-1", "agent-2", "agent-3"]
for agent_id in agent_ids:
    try:
        client.delete_agent(agent_id)
        print(f"Deleted agent {agent_id}")
    except Exception as e:
        print(f"Failed to delete {agent_id}: {e}")

🎯 Model Selection

Available Models

# List available models
models = client.list_language_models()

# Print model details
for model in models:
    print(f"Name: {model['name']}")
    print(f"Provider: {model['provider']}")
    print(f"Capabilities: {model.get('capabilities', [])}")
    print(f"Max tokens: {model.get('max_tokens', 'Unlimited')}")
    print()

Select Model for Agent

# Create agent with specific model
agent = client.create_agent(
    name="gpt4-agent",
    instruction="You are an advanced AI assistant.",
    model="gpt-4"
)

# Update existing agent's model
client.update_agent("agent-id", model="gpt-4-turbo")

🚨 Common Errors & Solutions

Authentication Errors

# Error: 401 Unauthorized
# Solution: Check your API key
aip config show
aip config set api_key "your-new-key"

Resource Not Found

# Error: 404 Not Found
# Solution: Verify agent exists
aip agents list
aip agents get <AGENT_ID>

Validation Errors

# Error: 422 Validation Error
# Solution: Check required fields
aip agents create --help

Timeout Errors

# Python: Increase timeout for complex tasks
agent = client.create_agent(
    name="complex-agent",
    instruction="Handle complex tasks",
    timeout=1800  # 30 minutes
)

# Or set per-run timeout
response = agent.run("Complex task", timeout=900)

📊 Best Practices

Agent Design

  1. Clear Instructions: Write specific, actionable instructions

  2. Appropriate Timeouts: Set realistic timeouts based on task complexity

  3. Tool Selection: Only attach tools the agent actually needs

  4. Model Selection: Choose models based on task requirements

Resource Management

  1. Clean Up: Always delete test agents when done

  2. Naming: Use descriptive names for easier management

  3. Documentation: Document agent purposes and configurations

  4. Monitoring: Track agent usage and performance

Security

  1. API Keys: Use environment variables, never hardcode

  2. Permissions: Limit agent access to necessary resources

  3. Validation: Validate all inputs before processing

  4. Logging: Monitor agent activities for security issues

🔗 Related Documentation

  • Tools Guide - Create and manage tools for agents

  • MCPs Guide - Connect external services

  • File Uploads - Upload files for agent processing

  • Streaming & Renderers - Control output format and streaming

🔗 Navigation

← Back to Guides Overview

Master agent creation, management, and execution with the AIP SDK!

PreviousGuidesNextTools