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, and run history plus scheduling remain REST-first.

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.

Create Agents

Python SDK

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"},
)

CLI

REST

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"))

CLI

REST

Update Agents

Python SDK

client.agents.update_agent(
    "agent-123",
    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

client.agents.delete_agent("agent-123")

CLI

REST

Run Agents

Basic Execution

Python SDK

response = client.agents.run_agent("agent-123", "Summarise the latest updates.")
print(response)

CLI

REST

With Files

Python SDK

with open("/tmp/report.pdf", "rb") as fh:
    response = client.agents.run_agent(
        "agent-123",
        "Review the attached report and highlight top risks.",
        files=[fh],
    )

CLI

REST

Runtime Overrides and PII

Python SDK

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

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?"},
]
client.agents.run_agent(
    "agent-123",
    "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.

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

coordinator = client.agents.create_agent(
    name="research-coordinator",
    instruction="Delegate research and compile final briefs.",
    agents=[researcher.id, analyst.id],
    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=completed" -H \
  "X-API-Key: $AIP_API_KEY" | jq '.data[] | {run_id, status, \
  created_at}'

Currently available via REST API; SDK and CLI support is under development. For now, use the REST endpoint in your monitoring or reporting scripts.

Scheduling

Centralised scheduling guidance now lives in the Automation & scripting guide. Follow that workflow to create, monitor, and audit recurring runs while SDK/CLI wrappers are still on the roadmap.

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.