Skip to main content
The Agents Service provides comprehensive management of AI agents through the Kubiya platform, including lifecycle management, access control, environment configuration, and tool integration.

​
Agents: detailed guide

This page focuses on the agent-specific parts of the SDK: creation, configuration, access control, environment variables, tool integration, and common patterns. If you haven’t set up a KubiyaClient yet, see the Client Quick Start at Client Overview for initialization and authentication instructions. Below are practical, in-depth examples and patterns for working with agents. The first example demonstrates creating a DevOps-focused agent and verifying the returned configuration.

​
Create an agent (devops-assistant example)

The example demonstrates creating a DevOps-focused agent, verifying it via client.agents.get, and inspecting returned fields such as uuid, name, llm_model, and tools. 
from kubiya import KubiyaClient
import time

client = KubiyaClient(api_key="your-api-key")

# Create a unique name to avoid collisions
name = f"devops-assistant-{int(time.time())}"

agent = client.agents.create(
  name=name,
  description="AI assistant for DevOps automation",
  llm_model="claude-sonnet-4",
  ai_instructions=(
    "You are a helpful DevOps assistant. Be clear and concise. "
    "Explain commands before execution and ask for confirmation for destructive actions."
  ),
  tools=["kubectl", "terraform"],
  integrations=["slack", "github"]
)

print(f"✅ Created agent: {agent.get('name')} (UUID: {agent.get('uuid')})")

# Verify details
details = client.agents.get(agent.get('uuid'))
print("✅ Verified agent details:")
print({k: details.get(k) for k in ("uuid", "name", "llm_model", "tools")})
Example output from a run of this flow (sanitized and factual from a real execution): 
🚀 Creating agent...
{
  "name": "devops-assistant-1764853010",
  "description": "AI assistant for DevOps automation",
  "llm_model": "claude-sonnet-4",
  "tools": [
    "kubectl",
    "terraform"
  ],
  "integrations": [
    "slack",
    "github"
  ]
}
✅ Created agent: devops-assistant-1764853010 (UUID: e9df18d2-a33f-4570-aafd-347e5018e047)
✅ Verified agent details:
{
  "uuid": "e9df18d2-a33f-4570-aafd-347e5018e047",
  "name": "devops-assistant-1764853010",
  "llm_model": "claude-sonnet-4",
  "tools": [
    "kubectl",
    "terraform"
  ]
}
The fields shown are exactly those returned by the client.agents.create and client.agents.get calls. Typical fields include uuid, name, llm_model, tools, integrations, and other configuration metadata. You can verify the same on the platform dashboard under Agents. SDK Agent Created

​
Core Operations

​
Create Agent

Create a new agent. Required: name. Optional: description, llm_model, ai_instructions, tools, integrations, and environment. 
agent = client.agents.create(
  name="my-assistant",
  description="A helpful AI assistant",
  llm_model="claude-sonnet-4",
  ai_instructions="You are a helpful assistant. Always be clear and concise.",
  tools=["kubectl", "docker"],
  integrations=["slack"],
  environment={"LOG_LEVEL": "INFO", "REGION": "us-east-1"}
)

​
List Agents

Retrieve a list of agents. Supports pagination and basic filtering via filter_term, sort_by, and limit. 
# List all agents
agents = client.agents.list(limit=10)

# With filtering
agents = client.agents.list(
    filter_term="devops",
    sort_by="created",
    limit=20
)

for agent in agents:
    print(f"{agent['name']}: {agent.get('description', 'No description')}")

​
Get Agent Details

Fetch a single agent’s full configuration and metadata by UUID. 
agent = client.agents.get("agent-uuid-here")
print(f"Agent: {agent['name']}")
print(f"Model: {agent['llm_model']}")
print(f"Tools: {agent.get('tools', [])}")

​
Update Agent

Update an agent’s configuration. Pass only the fields you wish to change; use add_tools/remove_tools for tool lists. 
client.agents.edit(
    "agent-uuid",
    llm_model="claude-opus-4",
    add_tools=["new-tool"],
    remove_tools=["old-tool"]
)

​
Delete Agent

Permanently remove an agent. This action cannot be undone; ensure you have the correct UUID. 
client.agents.delete("agent-uuid")

​
Access Control

Use the access subservice to view and modify who can interact with this agent (users and groups). Manage who can interact with your agents:

​
View Access Settings

Inspect current access lists for an agent (users and groups). 
access_info = client.agents.access.show("agent-uuid")
print(f"Allowed users: {access_info.get('users', [])}")
print(f"Allowed groups: {access_info.get('groups', [])}")

​
Add Users

Add specific user emails to the agent’s access allowlist. 
client.agents.access.add_user(
    "agent-uuid",
    ["[email protected]", "[email protected]"]
)

​
Add Groups

Add one or more groups to grant access to the agent (use your org’s group names). 
client.agents.access.add_group(
    "agent-uuid",
    ["devops-team", "engineering"]
)

​
Remove Access

Remove specific users or clear group restrictions. 
# Remove specific users
client.agents.access.remove_user("agent-uuid", ["[email protected]"])

# Clear all access restrictions (open access)
client.agents.access.clear("agent-uuid")

​
Environment Variables

Manage environment variables that will be present when the agent runs. Use env to avoid hardcoding secrets or configuration. Configure agent environment:

​
List Environment Variables

Retrieve the current key/value pairs set for the agent. 
env_vars = client.agents.env.list("agent-uuid")
for key, value in env_vars.items():
    print(f"{key}={value}")

​
Set Environment Variables

Set or update multiple environment variables for the agent. Values should be strings. 
client.agents.env.set("agent-uuid", {
    "API_ENDPOINT": "https://api.example.com",
    "TIMEOUT": "30",
    "DEBUG": "true"
})

​
Remove Environment Variables

Remove one or more environment variables from the agent’s runtime configuration. 
client.agents.env.unset("agent-uuid", ["DEBUG", "OLD_VAR"])

​
AI Instructions (Prompts)

Use the prompt API to set system-level instructions (a.k.a. system messages) that steer the agent’s LLM responses. Configure agent behavior with custom instructions:

​
Set Instructions

Set or replace the agent’s instruction block. This text guides the agent’s behavior and should be concise but explicit. 
instructions = """
You are a DevOps assistant specialized in Kubernetes and cloud infrastructure.

Guidelines:
- Always verify kubectl context before making changes
- Explain what each command does before executing
- Ask for confirmation for destructive operations
- Provide clear, step-by-step instructions
"""

client.agents.prompt.set("agent-uuid", instructions)

​
Get Current Instructions

Read back the currently configured instructions for the agent. 
current_prompt = client.agents.prompt.get("agent-uuid")
print(current_prompt)

​
Tool Management

Add or remove tool capabilities the agent can use when executing tasks. Tools are referenced by name. Manage agent capabilities:

​
Add Tools

Grant additional tools to the agent. Tools enable actions (e.g., kubectl, helm, terraform). 
client.agents.tools.add("agent-uuid", ["docker", "helm", "terraform"])

​
Remove Tools

client.agents.tools.remove("agent-uuid", ["old-tool"])

​
List Available Tools

tools = client.agents.tools.list_available()
for tool in tools:
    print(f"{tool['name']}: {tool['description']}")

​
Error Handling

Service-level errors raised by the Agents API should be handled to provide clear user feedback. 
from kubiya.kubiya_services.exceptions import AgentError

try:
    agent = client.agents.create(name="my-agent")
except AgentError as e:
    print(f"Failed to create agent: {e}")
    # Handle error appropriately

​
Complete Example

End-to-end example: create an agent, configure access and environment, and verify the agent is ready. 
from kubiya import KubiyaClient
from kubiya.kubiya_services.exceptions import AgentError

client = KubiyaClient()

try:
    # Create agent
    agent = client.agents.create(
        name="kubernetes-helper",
        description="Kubernetes management assistant",
        llm_model="claude-sonnet-4",
        ai_instructions="""
        You are a Kubernetes expert assistant.
        Always verify the cluster context before operations.
        Explain commands clearly.
        """,
        tools=["kubectl", "helm"],
        integrations=["slack"]
    )

    agent_uuid = agent['uuid']
    print(f"✅ Created agent: {agent['name']}")

    # Configure access
    client.agents.access.add_group(agent_uuid, ["devops-team"])
    print("✅ Added devops-team access")

    # Set environment
    client.agents.env.set(agent_uuid, {
        "CLUSTER": "production",
        "REGION": "us-east-1"
    })
    print("✅ Configured environment")

    # Verify
    agent_details = client.agents.get(agent_uuid)
    print(f"✅ Agent ready: {agent_details['name']}")

except AgentError as e:
    print(f"❌ Error: {e}")

​
Best Practices

# Good
agent = client.agents.create(name="production-k8s-assistant")

# Avoid
agent = client.agents.create(name="agent1")
Provide detailed instructions for consistent behavior:
instructions = """
Role: DevOps automation assistant
Responsibilities: Kubernetes management, deployment automation
Guidelines: Always verify context, explain actions, ask for confirmations
"""
client.agents.prompt.set(agent_uuid, instructions)
Restrict agent access to appropriate teams:
client.agents.access.add_group(agent_uuid, ["devops-team"])
# Don't leave agents with open access in production
Configure agents with environment variables instead of hardcoding:
client.agents.env.set(agent_uuid, {
    "CLUSTER": os.getenv("CLUSTER"),
    "REGION": os.getenv("REGION")
})

​
Next Steps

Examples

See real-world agent examples

API Reference

Complete API documentation