> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ziet.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoking

> Run your deployed agents via API, CLI, SDK, or Dashboard

## Overview

Once deployed, invoke your agents through multiple interfaces:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    ziet run my_agent --data '{"input": "value"}'
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://api.ziet.ai/agents/my_agent/run \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{"input": "value"}'
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from ziet import Client

    client = Client(api_key="your_key")
    result = client.run_agent("my_agent", {"input": "value"})
    ```
  </Tab>

  <Tab title="Dashboard">
    Go to [dashboard.ziet.ai](https://dashboard.ziet.ai/agents/my_agent) and click **Run Agent**
  </Tab>
</Tabs>

## Via CLI

### Basic Usage

```bash theme={null}
# 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:

```bash theme={null}
ziet run my_agent --data '{"input": "value"}' --follow
```

### Async Mode

Start run and return immediately:

```bash theme={null}
ziet run my_agent --data '{"input": "value"}' --async

# Returns: run_abc123

# Check status later
ziet status run_abc123
```

### CLI Options

<ParamField path="--data" type="string">
  JSON string of input data

  ```bash theme={null}
  ziet run my_agent --data '{"key": "value"}'
  ```
</ParamField>

<ParamField path="--data-file" type="string">
  Path to JSON input file

  ```bash theme={null}
  ziet run my_agent --data-file input.json
  ```
</ParamField>

<ParamField path="--param" type="string">
  Individual parameters (repeatable)

  ```bash theme={null}
  ziet run my_agent --param key1=value1 --param key2=value2
  ```
</ParamField>

<ParamField path="--follow" type="boolean">
  Stream logs in real-time
</ParamField>

<ParamField path="--async" type="boolean">
  Start run without waiting for completion
</ParamField>

<ParamField path="--env" type="string">
  Environment: `development` or `production`

  ```bash theme={null}
  ziet run my_agent --env production
  ```
</ParamField>

## Via API

### POST /agents/{agent_id}/run

**Request**:

```bash theme={null}
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):

```json theme={null}
{
  "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

```bash theme={null}
curl https://api.ziet.ai/runs/run_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**:

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

## Via Python SDK

### Install

```bash theme={null}
pip install ziet
```

### Basic Usage

```python theme={null}
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

```python theme={null}
# 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

<AccordionGroup>
  <Accordion title="run_agent()" icon="play">
    Run agent and wait for completion

    ```python theme={null}
    result = client.run_agent(
        agent_id="my_agent",
        data={"input": "value"},
        timeout=300  # Max wait time in seconds
    )
    ```
  </Accordion>

  <Accordion title="run_agent_async()" icon="bolt">
    Start run without waiting

    ```python theme={null}
    run = client.run_agent_async(
        agent_id="my_agent",
        data={"input": "value"}
    )
    # Returns immediately with run_id
    ```
  </Accordion>

  <Accordion title="get_run_status()" icon="info">
    Check run status

    ```python theme={null}
    status = client.get_run_status("run_abc123")
    print(status["status"])  # "running" | "completed" | "failed"
    ```
  </Accordion>

  <Accordion title="wait_for_run()" icon="clock">
    Wait for run to complete

    ```python theme={null}
    result = client.wait_for_run(
        run_id="run_abc123",
        timeout=300,
        poll_interval=2  # Check every 2 seconds
    )
    ```
  </Accordion>

  <Accordion title="cancel_run()" icon="stop">
    Cancel a running agent

    ```python theme={null}
    client.cancel_run("run_abc123")
    ```
  </Accordion>

  <Accordion title="list_runs()" icon="list">
    List recent runs

    ```python theme={null}
    runs = client.list_runs(
        agent_id="my_agent",
        limit=10,
        status="completed"
    )
    ```
  </Accordion>
</AccordionGroup>

## Via Dashboard

<Steps>
  <Step title="Navigate to agent">
    Go to [dashboard.ziet.ai/agents/my\_agent](https://dashboard.ziet.ai)
  </Step>

  <Step title="Click Run Agent">
    Click the **Run Agent** button
  </Step>

  <Step title="Fill input">
    Enter your input data in the form
  </Step>

  <Step title="Execute">
    Click **Execute** and watch real-time logs
  </Step>
</Steps>

The dashboard shows:

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

## Examples

### Python Script

```python theme={null}
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

```javascript theme={null}
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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Use async for long-running agents" icon="clock">
    ```python theme={null}
    # 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"])
    ```
  </Accordion>

  <Accordion title="Handle errors gracefully" icon="shield">
    ```python theme={null}
    try:
        result = client.run_agent("my_agent", data)
    except Exception as e:
        print(f"Agent failed: {e}")
        # Fallback logic
    ```
  </Accordion>

  <Accordion title="Set appropriate timeouts" icon="stopwatch">
    ```python theme={null}
    # 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)
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Monitoring" icon="chart-line" href="/deployment/monitoring">
    View logs and metrics
  </Card>

  <Card title="Deploying" icon="rocket" href="/deployment/deploying">
    Deploy your agents
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full API documentation
  </Card>

  <Card title="Agents" icon="robot" href="/core/agents">
    Learn about agents
  </Card>
</CardGroup>