Agents Guide

Master agent lifecycle operations, orchestration patterns, and runtime controls across the REST API, Python SDK, and CLI. This guide tracks the current production release and mirrors the capability matrix in the documentation overview.

For current REST, SDK, and CLI coverage, see the AIP capability matrix. Key callouts for agents: CLI still leans on export/import for tool_configs, memory toggles, and runtime overrides. Run history and scheduling are now available via SDK and REST.

CLI examples accept either an agent ID or a unique name for AGENT_REF. Partial matches trigger fuzzy search; add --select to disambiguate or pass the full ID when you need a deterministic lookup.

Execution Modes: Local vs Remote

See Local vs Remote Mode for detailed comparison and decision checklist.

Pattern Decision Guide

Choose the right pattern for your agent operations:

Agent-First Pattern (Recommended)

Use for creating and deploying single agents with simple configuration.

from glaip_sdk import Agent
from tools import CalculatorTool  # Your LangChain BaseTool class

agent = Agent(
    name="math-tutor",
    instruction="You are a patient tutor. Show working for every step.",
    tools=[CalculatorTool],  # Use LangChain BaseTool classes for local execution
    agent_config={"memory": "mem0"}
)

# Run the agent
result = agent.run("What is 15 * 23?")

Use this pattern for:

• Creating and running single agents

• Simple agent configuration

• Quick prototypes

• Self-contained agent operations

SDK Client Pattern (Secondary)

Use for listing, searching, and batch operations across multiple agents. This is a secondary pattern kept for backward compatibility and cross-agent workflows; prefer the Agent-first pattern for creating, updating, and running individual agents.

from glaip_sdk import Client

client = Client()

# Listing operations
agents = client.agents.list_agents(name="tutor")

# Batch operations
for agent in agents:
    print(f"Agent: {agent.name}")

# Advanced lifecycle management
agent = client.agents.get_agent_by_id("agent-123")

Use this pattern for:

• Listing and searching agents

• Batch operations across multiple agents

• Complex resource management workflows

• Multi-agent coordination

Features requiring Client pattern:

• Creating agents from JSON/YAML files (create_agent_from_file)

• Bulk listing and filtering agents

• LangFlow sync operations

• Run history retrieval via client.agents.runs

Use the Client pattern for these administrative and batch workflows.

---

Create Agents

Python SDK

Recommended: Agent Pattern

from glaip_sdk import Agent

agent = Agent(
    name="math-tutor",
    instruction="You are a patient tutor. Show working for every step.",
    tools=["time_tool"],  # String references require deploy() for remote execution
    agent_config={"memory": "mem0"}
)
agent.deploy()  # Required when using string tool references

Deprecated client pattern (still supported)

The older client.agents.create_agent API is kept for backward compatibility but new code should prefer the Agent pattern above for a simpler, low-code workflow and future improvements.

# Deprecated: prefer the Agent(...) pattern above
from glaip_sdk import Client

client = Client()

agent = client.agents.create_agent(
    name="math-tutor",
    instruction="You are a patient tutor. Show working for every step.",
    tools=["time_tool"],
    agent_config={"memory": "mem0"},
)

# `agent` is a glaip_sdk.agents.Agent instance, so you can call the same
# lifecycle methods as with the Agent(...) pattern
agent.run("What is 15 * 23?")

CLI

REST

In JSON definitions, disable planning by setting "planning": false in agent_config when you want a standard single-pass agent instead of a planning-enabled one.

Agent.deploy() will create a new agent when it does not exist yet, and update the existing definition when called again with the same reference. Use agent.update() when you already have a deployed Agent instance and want to change fields incrementally.

Need tool_configs, runtime overrides, or memory toggles from the CLI today? Export with aip agents get --export, edit the JSON, then re-import with aip agents create --import or aip agents update --import.

List and Inspect Agents

Python SDK

for agent in client.agents.list_agents(name="tutor"):
    print(agent.id, agent.name)

detail = client.agents.get_agent_by_id("agent-123")
print(detail.agent_config.get("lm_name"))

Note: client.agents.list_agents() and client.agents.get_agent_by_id() already return Agent instances, so you can call methods like agent.run(), agent.update(), or agent.delete() on the returned objects.

CLI

REST

Update Agents

Python SDK

# Assuming `agent` is an Agent instance
# (created with Agent(...) or loaded via client.agents.get_agent_by_id)
agent.update(
    instruction="Provide thorough financial analysis.",
    tools=["balance-sheet-parser", "chart-generator"],
    agent_config={"memory": "mem0", "tool_output_sharing": False},
    language_model_id="managed-finance-lm",
)

CLI

REST

Delete and Restore Agents

Python SDK

# Assuming `agent` is an Agent instance
agent.delete()  # Only needed if agent was deployed

CLI

REST

Run Agents

Basic Execution

Python SDK

Synchronous:

# Assuming `agent` is an Agent instance
response = agent.run("Summarise the latest updates.")
print(response)

Asynchronous (streaming):

import asyncio

async def main():
    async for chunk in agent.arun("Summarise the latest updates."):
        print(chunk, end="", flush=True)

asyncio.run(main())

Use agent.arun() when you need streaming responses or async integration.

CLI

REST

With Files

Python SDK

response = agent.run(
    "Review the attached report and highlight top risks.",
    files=["/tmp/report.pdf"],
)

CLI

REST

Runtime Overrides and PII

Python SDK

agent.run(
    "Produce a weekly revenue summary",
    pii_mapping={"<EMAIL_1>": "[e-mail]"},
    runtime_config={
        "agent_config": {
            "planning": False,
        },
        "tool_configs": {
            "revenue-sql": {"max_rows": 500, "group_by": "region"}
        },
        "mcp_configs": {
            "finance-data": {
                "authentication": {
                    "type": "api-key",
                    "value": "temporary-key"
                }
            }
        },
    },
)

Behind the scenes, Agent resolves tool_configs and mcp_configs using the global registries. This means you can define these configs against class-based Tool and MCP definitions, tool names, or IDs, and the SDK will map them to the correct resource IDs at deploy or run time.

Config key resolution: In runtime_config, you can reference tools and MCPs by:

• Custom LangChain tool class: {GreetingTool: {"param": "value"}} — your BaseTool subclass

• Tool helper instance: {Tool.from_native("time_tool"): {"param": "value"}} — a Tool reference

• MCP helper instance: {MCP.from_native("weather"): {"auth": {...}}} — an MCP reference

• Name string: {"greeting_tool": {"param": "value"}} — tool/MCP name on the remote server

• UUID: {"550e8400-e29b-...": {"param": "value"}} — direct ID registered in the server

Configuration priority order (lowest to highest):

Agent configurations are resolved in the following priority order, with higher priority overriding lower:

1. Agent definition configs (lowest priority) — agent_config, tool_configs, mcp_configs passed to Agent() constructor

2. Runtime config global — Top-level keys in runtime_config (e.g., runtime_config["tool_configs"])

3. Runtime config agent-specific (highest priority) — Agent-specific overrides in runtime_config[agent]

Example showing all three layers:

from glaip_sdk import Agent, Tool

# Layer 1: Agent definition configs (lowest priority)
agent = Agent(
    name="research-agent",
    instruction="...",
    tools=[ResearchTool],
    agent_config={"planning": False},  # Default: no planning
    tool_configs={
        ResearchTool: {"style": "brief", "max_results": 5}  # Defaults
    },
)

# Layer 2 & 3: Runtime overrides (higher priority)
agent.run(
    "Research AI trends",
    runtime_config={
        # Layer 2: Global runtime config
        "agent_config": {"planning": True},  # Override: enable planning
        "tool_configs": {
            ResearchTool: {"style": "detailed"}  # Override: detailed style
        },
        # Layer 3: Agent-specific runtime config (highest priority)
        agent: {
            "tool_configs": {
                ResearchTool: {"max_results": 10}  # Override: 10 results
            }
        }
    }
)

# Final resolved config for this run:
# - planning: True (from runtime global)
# - style: "detailed" (from runtime global)
# - max_results: 10 (from runtime agent-specific, highest priority)

This layered approach allows you to:

• Set sensible defaults at agent definition time

• Apply global overrides for all agents in a workflow

• Fine-tune specific agents with agent-specific overrides

REST

CLI

Chat History

Python SDK

history = [
    {"role": "user", "content": "We are drafting a security brief."},
    {"role": "assistant", "content": "Acknowledged. What scope should we cover?"},
]
agent.run(
    "Include external threat intel sources.",
    chat_history=history,
)

CLI

REST

Persist long-term context with agent_config.memory="mem0"; edit exports or use SDK kwargs until CLI flags arrive.

Planning Mode

Enable planning mode to have agents create a structured plan before executing complex tasks. This improves reasoning quality and task decomposition for multi-step queries.

Python SDK

from glaip_sdk import Agent
from tools import CalendarTool, TaskManagerTool  # Your LangChain BaseTool classes

agent = Agent(
    name="project-planner",
    instruction="You are a project manager. Break down tasks systematically.",
    tools=[CalendarTool, TaskManagerTool],
    agent_config={"planning": True},
)

# The agent will first create a plan, then execute each step
response = agent.run(
    "Create a launch plan for our new product release next month."
)

CLI

REST

Planning mode is especially useful for:

• Complex multi-step tasks that benefit from upfront reasoning

• Tasks requiring coordination across multiple tools

• Scenarios where transparency in the agent's approach is valuable

Timeouts and Limits

Setting	Default	Maximum	How to Change
Agent Runtime	5 minutes	No limit	Set timeout_seconds in agent_config
Step Limit	100 steps	1000 steps	Set in agent_config
Sub-Agent Levels	5 levels	10 levels	Set in agent_config

Tool Timeouts: Some tools have their own timeouts (like Browser Use tools), but these are separate from your agent timeout.

Long running agents: When building agents that need extended runtime (e.g., data analysis workflows, multi-step research tasks, or automated document processing), configure timeout_seconds appropriately. For long running agents that may take hours to complete, set a generous timeout and consider combining with retry configuration to handle transient failures. Remember that individual tools may have their own timeout limits that you cannot override.

Configuration: Timeout and Step Limit

Long running agents require careful timeout and step limit configuration to ensure they have enough time to complete complex tasks while preventing infinite loops. Use these settings to balance performance and task completion.

How to configure timeout and step limits in your agent:

Define agent_config in your agent class:

@property
def agent_config(self) -> dict:
    """Agent configuration with step limits and retry settings."""
    return {
        "timeout_seconds": 1800,  # 30 minutes
        "step_limit_config": {
            "max_steps": 100,  # Default limit
            "max_delegation_depth": 5,
        },
        "lm_retry_config": {
            "max_retries": 3,
            "initial_delay": 1.0,
            "max_delay": 30.0,
            "exponential_base": 2.0,
        },
    }

Configuration options:

Setting	Type	Default	Range	Description
timeout_seconds	int (seconds)	300	Any positive integer	Total runtime for the agent
max_steps	int	100	1-1000	Maximum number of agent actions/steps
max_delegation_depth	int	5	1-10	How deep sub-agents can be nested
max_retries	int	3	Any positive integer	LLM call retry attempts
initial_delay	float	1.0	Any positive float	Starting delay between retries (seconds)
max_delay	float	30.0	Any positive float	Maximum delay between retries (seconds)
exponential_base	float	2.0	Any positive float	Exponential backoff multiplier

Configuring long running agents:

• Data analysis workflows: Set timeout_seconds to 3600+ (1+ hour) for processing large datasets

• Multi-step research tasks: Increase max_steps to 500+ for complex research with multiple tools

• Document processing: Use max_delegation_depth of 5-10 for hierarchical document parsing

• Automated pipelines: Configure retry settings (max_retries, max_delay) to handle network or API rate limits

For long running agents, consider monitoring progress through logs or implementing checkpoint mechanisms if supported by your agent tools.

Multi-Agent Patterns

Need a refresher? The Multi-Agent System Patterns overview dives deep into hierarchies, routers, aggregators, and more. Use the snippet below as a quick starter.

Python SDK

from glaip_sdk import Agent

coordinator = Agent(
    name="research-coordinator",
    instruction="Delegate research and compile final briefs.",
    agents=[researcher, analyst],
    agent_config={"tool_output_sharing": True},
)

CLI

REST

See the Multi-Agent System Patterns overview for topology-specific examples (hierarchical, router, aggregator, sequential, parallel).

Iterate Quickly with Export and Import

CLI

aip agents get agent-123 --export agent.json
aip agents get agent-123 --export agent.yaml

aip agents create --import agent.json

Python SDK

REST

Iterate on Instructions Quickly

The CLI merges imports with flag overrides, so keep your definition in source control and loop quickly:

1. Export the agent — aip agents get prod-research --export prod-research.json captures the full payload (instruction, tool_configs, runtime defaults).

2. Edit locally — adjust instructions, swap language_model_id, or tighten tool settings. Commit the file so teammates can review changes.

3. Re-import — aip agents update prod-research --import prod-research.json applies the update immediately; any CLI flags you pass override the JSON.

4. Validate — run aip agents run prod-research --view md or --view json to confirm behaviour before moving to the next tweak.

Prefer IDs in scripts to avoid fuzzy matches, and branch your JSON when testing alternative prompts so you can compare diffs later. When you are ready to move between environments, follow the Configuration management guide for a full promotion checklist.

Observability

Run History

curl \
  -s "$AIP_API_URL/agents/agent-123/runs?status=success" -H \
  "X-API-Key: $AIP_API_KEY" | jq '.data[] | {run_id, status, \
  created_at}'

Use run_type=schedule to filter for scheduled runs only:

curl \
  -s "$AIP_API_URL/agents/agent-123/runs?run_type=schedule&status=success" -H \
  "X-API-Key: $AIP_API_KEY" | jq '.data[] | {run_id, status, \
  created_at}'

SDK support is available via client.schedules.list_runs(). CLI commands are under development.

Scheduling

Schedules run the same agent input on a recurring timetable in Asia/Jakarta (WIB). Create schedules with the SDK; REST examples live in the Automation & scripting guide. CLI commands are on the roadmap.

In the SDK, you can provide a cron string (minute hour day_of_month month day_of_week) or a ScheduleConfig object. REST scheduling uses the structured schedule object. Unspecified fields default to * (every).

Example (Python SDK):

from glaip_sdk import Client
from glaip_sdk.models.schedule import ScheduleConfig

client = Client()
agent = client.get_agent_by_id("agent-123")

# Create a schedule via the agent facade
schedule = agent.schedule.create(
    input="Generate daily summary report",
    schedule=ScheduleConfig(
        minute="0",
        hour="9",
        day_of_week="0-4",  # Weekdays at 9am WIB (Mon-Fri)
    ),
)
print(f"Next run: {schedule.next_run_time}")

# List runs for this schedule
runs = agent.schedule.list_runs(schedule.id)
for run in runs:
    if run.status == "success":
        result = run.get_result()
        print(f"Run {run.id} completed in {run.duration}")

See the Automation & scripting guide for cron formats, REST payloads, and full CRUD plus run history retrieval.

Troubleshooting

Issue	Symptoms	Resolution
Authentication errors	401 responses	Re-run aip configure or update Client(api_key=...).
Validation errors	422 responses	Check required fields with aip agents create --help or inspect error payloads.
Resource not found	404 responses	Confirm IDs with aip agents list or /agents filters.
Timeouts	AgentTimeoutError or HTTP 504	Increase timeout or review schedule load.

Best Practices

1. Scope instructions — concise prompts improve output quality.

2. Attach only necessary tools — reduces attack surface and execution time.

3. Reuse memory intentionally — enable mem0 when cross-run context adds value.

4. Audit run history — monitor /agents/{id}/runs for failure patterns or token usage.

5. Sanitise secrets — leverage pii_mapping and runtime MCP overrides to avoid persisting credentials.

Related Documentation

• Tools — manage native and custom tooling.

• MCPs — connect external systems and rotate credentials.

• Language models — choose language_model_id or provider/model pairs.

• Automation & scripting — orchestrate agents programmatically.

• Multi-Agent System Patterns overview — explore multi-agent coordination strategies.