Skip to main content

​
Overview

Once deployed, invoke your agents through multiple interfaces:
  • CLI
  • API
  • Python SDK
  • Dashboard
ziet run my_agent --data '{"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

​
--data
string
JSON string of input data
ziet run my_agent --data '{"key": "value"}'
​
--data-file
string
Path to JSON input file
ziet run my_agent --data-file input.json
​
--param
string
Individual parameters (repeatable)
ziet run my_agent --param key1=value1 --param key2=value2
​
--follow
boolean
Stream logs in real-time
​
--async
boolean
Start run without waiting for completion
​
--env
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 and wait for completion
result = client.run_agent(
    agent_id="my_agent",
    data={"input": "value"},
    timeout=300  # Max wait time in seconds
)
Start run without waiting
run = client.run_agent_async(
    agent_id="my_agent",
    data={"input": "value"}
)
# Returns immediately with run_id
Check run status
status = client.get_run_status("run_abc123")
print(status["status"])  # "running" | "completed" | "failed"
Wait for run to complete
result = client.wait_for_run(
    run_id="run_abc123",
    timeout=300,
    poll_interval=2  # Check every 2 seconds
)
Cancel a running agent
client.cancel_run("run_abc123")
List recent runs
runs = client.list_runs(
    agent_id="my_agent",
    limit=10,
    status="completed"
)

​
Via Dashboard

1

Navigate to agent

Go to dashboard.ziet.ai/agents/my_agent
2

Click Run Agent

Click the Run Agent button
3

Fill input

Enter your input data in the form
4

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

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

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

# 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