Skip to content
Athena Docs

Create an Agent

An agent is a published workflow with a system prompt, model configuration, and optional tools. Your app executes agents by ID — it never interacts with the underlying workflow graph.

What You Need First

  • A workspace with at least one LLM provider secret configured
  • Owner or Admin role

Agent Configuration

Each agent has a draft and one or more published versions. Your app always executes the latest published version.

FieldDescription
nameDisplay name shown in the admin UI and CMS storefront
descriptionShort description for the storefront card
system_promptInstructions injected before every execution
modelLLM provider and model identifier
api_enabledMust be true for API execution via eak_ keys
requires_user_messageWhether the execution request must include a message field

Workflow

A workflow is a directed graph of nodes. The engine walks it using BFS, starting from the Trigger node.

The simplest workflow has two nodes:

Trigger → Ai (LLM)

The LLM node carries the model config, temperature, max tokens, and optional output schema. Add more nodes for routing, memory, tools, or human approval — see Workflows for all node types.

Versioning

Publishing an agent creates an immutable version snapshot. Your app receives agent_version_id in execution responses so you can trace exactly which version ran.

ActionEffect
Edit draftNo effect on live executions
PublishNew version becomes active for all future executions
RollbackRe-publish a previous version

Agent ID Format

Agent IDs are raw UUIDv7 strings. Example: 019f902b-db6f-7ea4-8ef2-60a8ff5747cd.

Pass the raw UUID in the execution endpoint path:

POST /agents/019f902b-db6f-7ea4-8ef2-60a8ff5747cd/execute/stream

Groups

Agents can belong to groups. Groups allow shared configuration — LLM provider keys, default model, tool policies — applied to all agents in the group.

See Groups for details.