Agents

Master agent lifecycle operations, orchestration patterns, and runtime controls with the Python SDK. Use CLI pages for low-code operations. Use REST as reference-only for internal integrations (for example GLChat).

For current 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 available via the SDK; REST remains reference-only.

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

Client Pattern (Legacy/Advanced)

Use for listing, searching, and batch operations across multiple agents. This is a legacy/advanced pattern kept for backward compatibility and cross-agent governance 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

Client-only operations (legacy/advanced admin path):

• 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 only 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

aip agents create \
  --name math-tutor \
  --instruction "You are a patient tutor. Show working for every step." \
  --tools time_tool

curl \
  -X POST "$AIP_API_URL/agents" -H "Content-Type: application/json" -H \
  "X-API-Key: $AIP_API_KEY" -d '{
        "name": "math-tutor",
        "instruction": "You are a patient tutor. Show working for every step.",
        "tools": ["time_tool"],
        "agent_config": {"memory": "mem0"}
      }'

Specifying the Model

Agents use a default model (openai/gpt-5-nano) unless you specify otherwise. Use the model parameter with the standardized provider/model format:

Python SDK

Using Model Constants (Recommended):

from glaip_sdk import Agent
from glaip_sdk.models import OpenAI, DeepInfra, Anthropic

# OpenAI model
agent = Agent(
    name="analysis",
    instruction="You are a data analyst.",
    model=OpenAI.GPT_5_NANO,  # "openai/gpt-5-nano"
)

# DeepInfra model
agent = Agent(
    name="research",
    instruction="You are a research assistant.",
    model=DeepInfra.QWEN3_30B_A3B,  # "deepinfra/Qwen/Qwen3-30B-A3B"
)

# Anthropic model
agent = Agent(
    name="creative",
    instruction="You are a creative writer.",
    model=Anthropic.CLAUDE_SONNET_4_0,  # "anthropic/claude-sonnet-4-0"
)

Using String Format:

# OpenAI model
agent = Agent(
    name="analysis",
    instruction="You are a data analyst.",
    model="openai/gpt-5",
)

# DeepInfra model (includes organization in path)
agent = Agent(
    name="research",
    instruction="You are a research assistant.",
    model="deepinfra/Qwen/Qwen3-30B-A3B",
)

# Anthropic model
agent = Agent(
    name="creative",
    instruction="You are a creative writer.",
    model="anthropic/claude-sonnet-4-0",
)

Using Model Class (Custom Configuration):

from glaip_sdk import Agent
from glaip_sdk.models import Model

# Custom model with credentials and hyperparameters
agent = Agent(
    name="custom-model",
    instruction="You are helpful.",
    model=Model(
        id="custom/kimi-k2.5",
        base_url="https://api.moonshot.ai/v1",
        credentials="sk-xxxx",
        hyperparameters={
            "temperature": 1.0,
            "max_tokens": 32768,
        },
    ),
)

CLI

REST

Model Constants: Import typed constants from glaip_sdk.models for better IDE support and validation:

• from glaip_sdk.models import OpenAI, Anthropic, Google, AzureOpenAI, DeepInfra, DeepSeek, Bedrock

• Use from glaip_sdk.models import DEFAULT_MODEL to see the current default

See the Language models for the complete list of available models.

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

aip agents list

aip agents get agent-123 --view json

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

cat > agent-update.json <<'JSON'
{
  "instruction": "Provide thorough financial analysis.",
  "agent_config": {
    "memory": "mem0",
    "tool_output_sharing": false
  },
  "language_model_id": "managed-finance-lm"
}
JSON

aip agents update agent-123 --import agent-update.json

Delete and Restore Agents

Python SDK

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

CLI

aip agents delete agent-123

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

aip agents run agent-123 --input "Summarise the latest updates."

With Files

Python SDK

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

CLI

aip \
  agents run agent-123 --input "Review the attached report and highlight \
  top risks." --file /tmp/report.pdf

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

CLI

pii_mapping and runtime_config flags are in development. Use the SDK or REST API for sensitive workflows until dedicated options land.

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

HISTORY='[{"role":"user","content":"We are drafting a security brief."}]'
aip \
  agents run agent-123 --input "Include external threat intel sources." \
  --chat-history "$HISTORY"

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

cat > planner-agent.json <<'JSON'
{
  "name": "project-planner",
  "instruction": "You are a project manager. Break down tasks systematically.",
  "agent_config": {
    "planning": true
  }
}
JSON

aip agents create --import planner-agent.json

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.

GL Connectors Token

gl_connectors_token is a remote-only feature. It is forwarded to the platform's /agents/{agent_id}/run endpoint and has no effect on local runs. Deploy your agent with agent.deploy() before using this parameter.

Use the gl_connectors_token parameter when your remote run can invoke native tools or MCPs that require end-user auth via GL Connectors.

• When required: at least one reachable integration (native tool or MCP) has user_authentication=true in its tool_configs or mcp_configs.

• Execution scope: per-run only; it is not stored in the deployed agent definition.

• Transport support: forwarded in both JSON-only runs and multipart runs with file attachments.

Python SDK

# JSON run (agent must be deployed first)
agent.deploy()

result = agent.run(
    "Summarise my recent CRM activities",
    gl_connectors_token="<user-token>",
)

# Multipart run (with files)
result = client.agents.run_agent(
    agent.id,
    "Review the attached report and sync notes",
    files=["/tmp/report.pdf"],
    gl_connectors_token="<user-token>",
)

With a native tool (BOSA): configure user_authentication=True in tool_configs at agent initialization, deploy, then pass gl_connectors_token at run time:

from glaip_sdk import Agent, Tool

agent = Agent(
    name="bosa-agent",
    instruction="Search BOSA records and summarize highlights.",
    tools=[Tool.from_native("bosa_google_drive_search_files_tool")],
    tool_configs={
        "bosa_google_drive_search_files_tool": {
            "user_authentication": True,
        }
    },
)
agent.deploy()

result = agent.run(
    "Search my BOSA records and summarize highlights",
    gl_connectors_token="<user-token>",
)

With an MCP: configure user_authentication=True in mcp_configs at agent initialization, deploy, then pass gl_connectors_token at run time:

from glaip_sdk import Agent, MCP

agent = Agent(
    name="crm-agent",
    instruction="Summarise CRM activities.",
    mcps=[MCP.from_native("crm_mcp")],
    mcp_configs={
        "crm_mcp": {
            "user_authentication": True,
        }
    },
)
agent.deploy()

result = agent.run(
    "Summarise my recent CRM activities",
    gl_connectors_token="<user-token>",
)

If the token is missing/invalid for required integrations, the run can fail early with backend auth or precheck errors (for example 403/409), which helps prevent partial execution with unauthenticated integrations.

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

aip \
  agents create --name research-coordinator --instruction "Delegate \
  research and compile final briefs." \
  --agents researcher \
  --agents analyst

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

agent = client.agents.get_agent_by_id("agent-123")
with open("agent-123.json", "w") as fh:
    fh.write(agent.model_dump_json(indent=2))

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 for a full promotion checklist.

Observability

Run History

Python SDK:

from glaip_sdk import Client

client = Client()
runs = client.agents.runs.list_runs(agent_id="agent-123", limit=20, page=1)

successful = [r for r in runs.data if r.status == "success"]
for run in successful:
    print(run.id, run.status, run.created_at)

CLI (local transcript cache):

/transcripts

/transcripts opens the local transcript history; select a run in the browser to inspect details.

Debug Remote Runs (Interactive /runs + SDK Run Detail)

Use this when a deployed agent behaves unexpectedly (tool failures, timeouts, inconsistent outputs) and you need an audit trail you can share.

1. Trigger a remote run with a reproducible input.

2. Capture the run ID (it appears in the streaming metadata and in run history).

3. Inspect tool calls, errors, and final output from the run record.

CLI (interactive remote runs browser):

# Open the slash palette
aip

Inside the palette:

1. Run /agents and select the agent you want to debug.

2. Run /runs to browse that agent's remote run history.

3. Open a run to view the full transcript and export it if needed.

Screenshot placeholder: /runs table view with a selected run, plus the run detail panel showing tool calls and final output.

Python SDK (fetch run output events):

from glaip_sdk import Client

client = Client()
agent_id = "agent-123"

# Pick the most recent run (page 1 is typically newest-first).
runs = client.agents.runs.list_runs(agent_id=agent_id, limit=1, page=1)
run_id = str(runs.data[0].id)

run = client.agents.runs.get_run(agent_id=agent_id, run_id=run_id)
print("status:", run.status)

# Print tool calls captured in agent_step events (best-effort; payloads vary by tool/framework).
for ev in run.output:
    meta = ev.get("metadata") or {}
    if meta.get("kind") not in ("agent_step", "agent_thinking_step"):
        continue
    for call in meta.get("tool_calls") or []:
        print(call.get("name"), call.get("args"))

Common debugging patterns:

• If the run ends early, search run.output for metadata.kind == "error" or terminal events (final_response, error, step_limit_exceeded).

• If a tool is misbehaving, compare the tool call args from the run transcript against your expected schema and defaults (tool_configs).

• If a run is inconsistent, export the agent definition and diff it across environments, then re-run with identical inputs and runtime overrides.

Scheduling

Schedules run the same agent input on a recurring timetable in Asia/Jakarta (WIB). Create schedules with the SDK; CLI commands are on the roadmap. REST documentation exists as reference only in Resources.

In the SDK, you can provide a cron string (minute hour day_of_month month day_of_week) or a ScheduleConfig 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.agents.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, full CRUD, and run history retrieval.

Troubleshooting

Issue	Symptoms	Resolution
Authentication errors	401 responses	Re-run aip accounts add <name> + aip accounts use <name>, 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 client.agents.list_agents().
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 — review recent runs via client.agents.runs.list_runs(...) and CLI transcripts for failure patterns.

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 — configure models using provider/model format or Model class.

• Automation & scripting — orchestrate agents programmatically.

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