Agents Guide

Agents in Anchor represent AI entities with persistent identity, lifecycle management, and associated resources. Every agent has a unique ID that follows it across sessions, deployments, and infrastructure.

What is an Agent?

An agent is a registered AI entity with:

• Unique identity: Persistent ID that never changes
• Metadata: Name, description, owner, tags
• Lifecycle state: Active, suspended, or deleted
• Associated resources: Data, permissions, audit logs

Creating Agents

Basic Agent

from anchor import Anchor

anchor = Anchor(api_key="anc_...")

# Create an agent
agent = anchor.agents.create(name="my-agent")
print(f"ID: {agent.id}")

Agent with Metadata

agent = anchor.agents.create(
    name="support-bot",
    description="Handles customer support inquiries",
    owner="team:support",
    tags=["production", "customer-facing"],
    metadata={
        "version": "2.0",
        "model": "gpt-4",
        "department": "support"
    }
)

Getting Agents

Get by ID

agent = anchor.agents.get("agt_abc123")

if agent:
    print(f"Name: {agent.name}")
    print(f"Status: {agent.status}")

List Agents

# List all agents
agents = anchor.agents.list()

# Filter by status
active_agents = anchor.agents.list(status="active")

# Filter by owner
team_agents = anchor.agents.list(owner="team:support")

Agent Lifecycle

Agents go through these states: created → active ↔ suspended → deleted

Suspend an Agent

# Suspend - agent can't act but data is preserved
anchor.agents.suspend(agent.id)

# Check status
agent = anchor.agents.get(agent.id)
print(agent.status)  # "suspended"

Activate an Agent

anchor.agents.activate(agent.id)

agent = anchor.agents.get(agent.id)
print(agent.status)  # "active"

Delete an Agent

# Delete agent and associated resources
anchor.agents.delete(agent.id)

# Optionally keep audit logs
anchor.agents.delete(agent.id, preserve_audit=True)

Best Practices

• Use descriptive names (e.g., "customer-support-v2" not "agent1")
• Set owners to track responsibility
• Use tags for organization (environment, purpose, version)
• Store relevant metadata (version, model, framework, department)
• Handle errors gracefully
• Clean up unused agents regularly

TypeScript Example

import { Anchor } from 'anchorai';

const anchor = new Anchor({ apiKey: 'anc_...' });

// Create agent
const agent = await anchor.agents.create({
  name: 'support-bot',
  description: 'Customer support agent',
  owner: 'team:support',
  tags: ['production']
});

console.log(`Agent ID: ${agent.id}`);

// Get agent
const fetched = await anchor.agents.get(agent.id);

// List agents
const agents = await anchor.agents.list({ status: 'active' });

// Suspend/activate
await anchor.agents.suspend(agent.id);
await anchor.agents.activate(agent.id);

// Delete agent
await anchor.agents.delete(agent.id);

For more details, see the API reference.