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

# Agents

> Create, manage, and chat with agents using the Pawa AI Python SDK.

Agents are available under `client.agents`. Chat with an agent via `client.agents.chat.create(...)`, which supports non-streaming and streaming the same way as chat. See the [Agents API reference](/api-reference/endpoint/agents/introduction).

## Create an agent

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

agent = client.agents.create(
    name="TutorAI",
    description="TutorAI helps students with secondary school subjects.",
    instruction=(
        "Teach Form 1–4 subjects. Answer only academic questions "
        "related to the assigned curriculum."
    ),
    intents=["Be gentle", "Be detailed"],
    knowledgeBaseId=159,
    tools=[{"type": "pawa_tool", "name": "web_search_tool"}],
)

print(agent)
```

## List and retrieve

```python theme={null}
agents = client.agents.list()
print(agents)

agent = client.agents.retrieve(agent_id=42)
print(agent)
```

## Update and delete

```python theme={null}
updated = client.agents.update(
    42,
    name="TutorAI v2",
    description="Updated tutoring agent",
    instruction="Focus on math and science.",
)
print(updated)

deleted = client.agents.delete(42)
print(deleted)
```

## Agent chat (non-streaming)

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.agents.chat.create(
    model="pawa-v1-ember-20240924",
    message={
        "role": "user",
        "content": [{"type": "text", "text": "Explain photosynthesis simply."}],
    },
    agents=[42],
    stream=False,
)

print(response)
```

## Agent chat (streaming)

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

with client.agents.chat.create(
    model="pawa-v1-ember-20240924",
    message={
        "role": "user",
        "content": [{"type": "text", "text": "Summarize Newton's three laws."}],
    },
    agents=[42],
    stream=True,
) as stream:
    for delta in stream.text_deltas():
        print(delta, end="", flush=True)
    print()
    print(stream.collect())
```

## Handoff / multi-agent

Pass multiple agent IDs so a router can hand off to specialists:

```python theme={null}
response = client.agents.chat.create(
    model="pawa-v1-blaze-20250318",
    message={
        "role": "user",
        "content": [{"type": "text", "text": "Help me with algebra homework."}],
    },
    agents=[10, 11, 12],
    stream=False,
)

print(response)
```