Build an AI agent

An AI agent in Alpha is a set of model-driven steps you describe in words. Alpha writes it as real code for an agent framework, proves it works, and draws it on the Agent tab. If you want an app feature that calls a model, such as a smart search, describe the app instead: Alpha builds that as ordinary app code. To run an agent that’s already built, see Try your agent.

​

What does Alpha build?

Every agent is one folder, /workspace/<name>, called the agent tree. At its root, definition.yaml names the workers, their steps and order, the inputs and the fields of the answer, and tools/ holds the Python functions the steps call. Alpha’s agent compiler, Stormlight, turns that description into a project for a framework, in its own folder inside the tree. It’s plain framework code you own and can run anywhere. Open any of it from Files. Ask for more than one (“also write it for LangGraph”) and each framework gets its own folder in the same tree. Try it lets you pick which one a message runs on.

​

Ask for an agent

Say “agent” in so many words, in your first message or later in a session. Alpha goes by your words, not by what the task seems to need. “An app for real estate agents” and “no agents, just a CRUD app” land in the last row too. Alpha will:

1. Ask about the agent’s shape and inputs, unless your message already says.
2. Say the plan back in one sentence: the framework, the steps and their order.
3. Draw the agent on the Agent tab while it is still being proved.
4. Prove it, including one live run on your key, and publish it.

​

Answer the question card

When the shape is open, the agent shows one question card before writing anything: two or three questions, recommended option first. Pick an option or type into Something else…, then click Send answers. Skip — let the agent decide takes every recommendation, and “just build it” in your message skips the card. The plan sentence names every default it assumed. Once the agent is published, it may ask once whether you want a small page around it. Declining ends the matter.

​

How Alpha proves the agent

Every agent goes through five stages before it’s published. A failing stage names the field to change, and the agent fixes it and proves again. The graph appears on the Agent tab as soon as the description is valid, marked as not proved, so you can read it during the proof. Once the agent is proved live and published, a card asks Test this agent with evals?. Nothing runs until you say yes: see Set up evals.

​

Add the keys it needs

The live run reads the key the description names, usually OPENAI_API_KEY. The agent looks for it in your secrets by name, confirms an OpenAI key with one tiny request, and tells you which model and key it is building on. Another provider’s key, such as ANTHROPIC_API_KEY for the Claude Agent SDK, is checked by the live run itself. A Lyzr agent also needs LYZR_API_KEY. With no model key, or no Lyzr key for a Lyzr agent, it asks: “This agent needs a live OpenAI key to prove it works. Add one now?” For a Lyzr agent, the question names Lyzr.

​

Change the agent

Ask the agent. It edits the tree’s root, redraws the graph, proves every framework folder again and republishes. Don’t edit a generated framework folder by hand: the next build rewrites it.

​

What can’t an agent do yet?

​

Turn the agent builder off

Building agents is a skill, Agent builder, that ships with Alpha. Click Skills in the sidebar and, on the Installed tab, switch its row off, or open it and turn off Installed in your sessions. That changes your sessions only. With it off, an attempt to build stops with “stormlight is off for this session (switch on the agent-builder skill in Skills)”. An agent already on the Agent tab still draws and runs. Skills that ship with Alpha covers the admin switches.

​

Next steps