Invoking

Overview

Once deployed, invoke your agents through multiple interfaces:

CLI
API
Python SDK
Dashboard

ziet run my_agent --data '{"input": "value"}'

curl -X POST https://api.ziet.ai/agents/my_agent/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"input": "value"}'

from ziet import Client

client = Client(api_key="your_key")
result = client.run_agent("my_agent", {"input": "value"})

Via CLI

Basic Usage

# Run agent
ziet run my_agent

# With JSON data
ziet run my_agent --data '{"origin": "SFO", "dest": "NYC"}'

# With individual parameters
ziet run my_agent --param origin=SFO --param dest=NYC

# From file
ziet run my_agent --data-file input.json

Stream Logs

Follow execution in real-time:

ziet run my_agent --data '{"input": "value"}' --follow

Async Mode

Start run and return immediately:

ziet run my_agent --data '{"input": "value"}' --async

# Returns: run_abc123

# Check status later
ziet status run_abc123

CLI Options

string

JSON string of input data

ziet run my_agent --data '{"key": "value"}'

string

Path to JSON input file

ziet run my_agent --data-file input.json

string

Individual parameters (repeatable)

ziet run my_agent --param key1=value1 --param key2=value2

boolean

Stream logs in real-time

boolean

Start run without waiting for completion

string

Environment: development or production

ziet run my_agent --env production

Via API

POST /agents//run

Request:

curl -X POST https://api.ziet.ai/agents/my_agent/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "SFO",
    "dest": "NYC",
    "date": "2024-12-25"
  }'

Response (200 OK):

{
  "run_id": "run_abc123xyz",
  "agent_id": "my_agent",
  "status": "completed",
  "result": {
    "flights_found": 42,
    "best_price": 350
  },
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:12Z",
  "duration_ms": 12000
}

Status Codes

200 - Run completed successfully
202 - Run accepted (async mode)
400 - Invalid input
401 - Unauthorized (check API key)
404 - Agent not found
500 - Internal error

Get Run Status

curl https://api.ziet.ai/runs/run_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "run_id": "run_abc123",
  "status": "running",
  "progress": 45,
  "started_at": "2024-01-15T10:30:00Z"
}

Via Python SDK

Install

pip install ziet

Basic Usage

from ziet import Client

# Initialize
client = Client(api_key="your_api_key")

# Run agent (synchronous - waits for completion)
result = client.run_agent(
    agent_id="my_agent",
    data={"origin": "SFO", "dest": "NYC"}
)

print(result)
# {"flights_found": 42, "best_price": 350}

Async Mode

# Start run without waiting
run = client.run_agent_async(
    agent_id="my_agent",
    data={"origin": "SFO", "dest": "NYC"}
)

print(f"Run started: {run['run_id']}")

# Check status
status = client.get_run_status(run["run_id"])
print(f"Status: {status['status']}")

# Wait for completion
result = client.wait_for_run(
    run_id=run["run_id"],
    timeout=300  # 5 minutes
)

SDK Methods

run_agent()

Run agent and wait for completion

result = client.run_agent(
    agent_id="my_agent",
    data={"input": "value"},
    timeout=300  # Max wait time in seconds
)

run_agent_async()

Start run without waiting

run = client.run_agent_async(
    agent_id="my_agent",
    data={"input": "value"}
)
# Returns immediately with run_id

get_run_status()

Check run status

status = client.get_run_status("run_abc123")
print(status["status"])  # "running" | "completed" | "failed"

wait_for_run()

Wait for run to complete

result = client.wait_for_run(
    run_id="run_abc123",
    timeout=300,
    poll_interval=2  # Check every 2 seconds
)

cancel_run()

Cancel a running agent

client.cancel_run("run_abc123")

list_runs()

List recent runs

runs = client.list_runs(
    agent_id="my_agent",
    limit=10,
    status="completed"
)

Via Dashboard

Navigate to agent

Go to dashboard.ziet.ai/agents/my_agent

Click Run Agent

Click the Run Agent button

Fill input

Enter your input data in the form

Execute

Click Execute and watch real-time logs

The dashboard shows:

Real-time execution logs
Action calls
Memory operations
Final result
Execution time

Examples

Python Script

from ziet import Client

client = Client(api_key="your_api_key")

# Run research agent
result = client.run_agent(
    agent_id="research_agent",
    data={
        "topic": "artificial intelligence",
        "depth": "deep",
        "max_results": 20
    }
)

print(f"Summary: {result['summary']}")
print(f"Sources: {result['sources']}")

Node.js Script

const axios = require('axios');

async function runAgent() {
  const response = await axios.post(
    'https://api.ziet.ai/agents/my_agent/run',
    {
      origin: 'SFO',
      dest: 'NYC',
      date: '2024-12-25'
    },
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );
  
  console.log(response.data);
}

runAgent();

cURL

# Simple invocation
curl -X POST https://api.ziet.ai/agents/my_agent/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "value"
  }'

# With pretty output
curl -X POST https://api.ziet.ai/agents/my_agent/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin": "SFO", "dest": "NYC"}' \
  | jq .

Best Practices

Use async for long-running agents

# For agents that take > 30 seconds
run = client.run_agent_async(agent_id="my_agent", data={...})

# Do other work...

# Check back later
result = client.wait_for_run(run["run_id"])

Handle errors gracefully

try:
    result = client.run_agent("my_agent", data)
except Exception as e:
    print(f"Agent failed: {e}")
    # Fallback logic

Set appropriate timeouts

# Short timeout for quick agents
result = client.run_agent("quick_agent", data, timeout=30)

# Longer timeout for complex agents
result = client.run_agent("complex_agent", data, timeout=300)

Next Steps

Monitoring

View logs and metrics

Deploying

Deploy your agents

API Reference

Full API documentation

Agents

Learn about agents

Getting Started

Agentic

Application

Integrations

Deployment

Overview

Via CLI

Basic Usage

Stream Logs

Async Mode

CLI Options

Via API

POST /agents//run

Status Codes

Get Run Status

Via Python SDK

Install

Basic Usage

Async Mode

SDK Methods

Via Dashboard

Examples

Python Script

Node.js Script

cURL

Best Practices

Next Steps

Monitoring

Deploying

API Reference

Agents

​Overview

​Via CLI

​Basic Usage

​Stream Logs

​Async Mode

​CLI Options

​Via API

​POST /agents//run

​Status Codes

​Get Run Status

​Via Python SDK

​Install

​Basic Usage

​Async Mode

​SDK Methods

​Via Dashboard

​Examples

​Python Script

​Node.js Script

​cURL

​Best Practices

​Next Steps

Monitoring

Deploying

API Reference

Agents

Overview

Via CLI

Basic Usage

Stream Logs

Async Mode

CLI Options

Via API

POST /agents//run

Status Codes

Get Run Status

Via Python SDK

Install

Basic Usage

Async Mode

SDK Methods

Via Dashboard

Examples

Python Script

Node.js Script

cURL

Best Practices

Next Steps