Skip to main content

Getting Started

The Zeta Alpha agents SDK ships a production-ready agent harness - an agent that already knows how to search, cite, remember, and delegate. You teach it about your domain through configuration: your tools, your skills, your instructions. You'll have it running locally in a few minutes.

Prerequisites​

  • Python 3.10 or higher
  • (Optional) A Zeta Alpha tenant (for connecting straight to your internal knowledge and shipping to your users) - sign up here if you don't have one yet

Step 1: Install the SDK​

pip install zetaalpha.agents

Verify the installation:

za agents --help

Step 2: Initialize a Project​

za agents init

The wizard asks for your LLM provider and API key, then creates your project:

agents/
├── agent_setups.json       ← agents (reference LLM configurations by name)
├── llm_configurations.json ← named LLM configurations
├── __init__.py             ← extend with custom agent code
├── skills/                 ← skill folders
├── instructions/           ← instruction files
├── specs/                  ← behavior tests
├── memories/               ← local memory (gitignored)
└── env/
    └── secrets.json        ← credentials, by name (gitignored)

Step 3: Explore Your Agent Configuration​

The project is already configured with the built-in agent. View it with:

za agents show
╭────────────────────────────────────────────────────────────────────╮
│ Project  agents                                                    │
│ Agent    agent built-in                                            │
│ Model    gpt-5.4-mini (openai)                                     │
╰────────────────────────────────────────────────────────────────────╯
                       Capabilities
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Provider           ┃ Status   ┃ Sources / Details       ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Tools              │ enabled  │ 0/18 tool-sets          │
│ Skills             │ enabled  │ 2/7 skill-sources       │
│ Memory             │ enabled  │ 1/5 memory-stores       │
│ Context            │ enabled  │ 0/9 context-sources     │
│ Instructions       │ enabled  │ 1/7 instruction-sources │
│ Agent Delegation   │ enabled  │ 0/1 delegation-sources  │
│ Message Processing │ enabled  │ 0/2 processors          │
│ Dispatch           │ disabled │                         │
│ Interjections      │ disabled │                         │
│ Python REPL        │ disabled │                         │
│ MCP Tools          │ enabled  │ 0 mcp-servers           │
└────────────────────┴──────────┴─────────────────────────┘

Skills        0 files in skills/
Instructions  0 files in instructions/
Specs         0 files in specs/

The agent configuration lives in agent_setups.json, which the CLI helps you manage - you rarely need to edit it by hand. API keys are stored separately, by name, in env/secrets.json, which is gitignored and never committed.

tip

To understand what each capability does and how the agent assembles them, see How the Agent Harness Works.

Step 4: Run Locally​

Start the interactive dev environment:

za agents dev

The command opens a browser window where you can chat with the agent and change its configuration.

Or start the REST API server:

za agents serve

The API documentation is available at http://localhost:8000/docs. Test your agent:

curl -X POST "http://localhost:8000/chats/responses?tenant=your-tenant" \
-H "Content-Type: application/json" \
-d '{
  "agent_identifier": "agent",
  "conversation": [{"sender": "user", "content": "Hello"}]
}'

This is the same Chat API used by the Zeta Alpha platform. For the full API reference, streaming, and integration details, see Getting Started with the Chat API.

info

When running locally with the CLI, the agent reads its configuration from the local agent_setups.json files. When deployed to the Zeta Alpha platform, the configuration is stored in your tenant.

warning

The za agents serve endpoint does not include authentication or authorization. If you expose it directly, you are responsible for adding your own auth layer. The chat API expects Authorization (JWT) or X-Auth (API key) headers. When deployed to the Zeta Alpha platform, authentication and authorization are handled for you.

Step 5: Manage Your Agent with the CLI​

Here are some common commands:

za agents model configure gpt-5.4-mini          # change the LLM model
za agents skill add                             # create a new skill
za agents capabilities memory-stores settings   # configure memory
za agents capabilities tool-sets list           # list available tool sources
za agents show                                  # project overview

What to Do Next​

Before diving into specific capabilities, read How the Agent Harness Works to see the full menu of what the agent can do and find the right guide for your use case.

Then follow the tutorials in order:

  1. Explore the dev sandbox - try different configurations, review debug output, and iterate quickly: → Exploring the Dev Sandbox

  2. Enable capabilities - add tools, skills, memory, and delegation through the CLI: → Configuring Capabilities with the CLI

  3. Deploy to the platform - bundle your project and upload it: → Deploying Agents

  4. Manage in the platform - configure agents in the UI and assign them to surfaces: → Managing Agents in the Platform

Or jump to a specific guide: Configuring Tools | Using Agent Skills | Integrating via the Chat API