How to Set Up Automata and Run Your First Agent

Automata is an open-source, self-programming AI system that uses large language models (such as GPT-4) and a vector database to document, search, and write code. To get it running, follow the project's setup guide to create a local environment and install dependencies, then configure an agent with OpenAIAutomataAgentConfigBuilder and run it through the agent CLI with a simple instruction to confirm everything works. The steps below reflect what the documentation currently covers; because the docs are described as a work in progress, expect some sections to be thin.

Prerequisites

• A local development environment where you can install Python dependencies (the setup guide is titled "Create Local Environment").
• Access to an LLM provider. The documentation's agent configuration centers on OpenAI models like GPT-4, so plan on having an OpenAI-compatible API credential available.
• Basic familiarity with running CLI commands and editing configuration files.

The documentation does not publish pricing or account-tier details for Automata itself, so treat any provider costs as coming from your LLM API usage rather than from Automata.

Step 1: Create the local environment

Start from the project's setup guide, which walks through creating a local environment and installing dependencies. In practice this means:

1. Clone the repository from the GitHub page linked in the docs.
2. Create and activate a virtual environment.
3. Install the project's dependencies.

Expected result: an activated environment where the automata package and its CLI are importable. Common snag: the docs note that module documentation is auto-generated via the run-doc-embedding pipeline and still incomplete, so if a dependency step is ambiguous, cross-check against the repository's own install files rather than the rendered docs alone.

Step 2: Configure the agent

Agent behavior is configured through OpenAIAutomataAgentConfigBuilder, documented under the Agent Guide alongside OpenAIAutomataAgent. The builder is where you supply the model and agent settings before constructing the agent. You will also need your provider credentials available to the process (typically via environment variable, per your provider's convention).

A minimal configuration pattern looks like this:

from automata.agent import OpenAIAutomataAgentConfigBuilder, OpenAIAutomataAgent

config = (
    OpenAIAutomataAgentConfigBuilder()
    .with_model("gpt-4")          # model name per your provider
    .build()
)

agent = OpenAIAutomataAgent(config=config)

Check the Agent Guide page for the exact builder methods your installed version exposes — the documentation lists the classes but the auto-generated module pages are the authoritative reference for method names.

Step 3: Run the agent CLI with a simple instruction

The docs list an agent CLI entry point under the setup section. Use it to run a trivial instruction first, so a failure is easy to isolate:

automata agent "List the files in the current directory and summarize what this project does"

Expected result: the agent accepts the instruction, calls the model, and returns a response or tool action. Common snags:

• Missing credentials: the agent will fail at the first model call. Confirm your API key is exported in the same shell.
• Import or path errors: usually mean the environment from Step 1 isn't active.
• Empty or partial output: the docs describe the agent as capable of both trivial and non-trivial instruction execution; start trivial and scale up only after a clean run.

Step 4: Verify and extend

Once a trivial instruction succeeds, you have a working baseline. From there the documented feature path runs roughly in order of complexity:

If you want the agent to search your own code, the "Creating Your Own Embeddings" guide covers configuring the pyright-scip repository, updating code embeddings, and building and embedding the docs. The FAQ page is the place to check when a step behaves differently from the guide.

When this approach fits

This setup path suits developers who want to run Automata locally and experiment with an autonomous coding agent on their own machine. If you only need to read about the architecture, the GitHub page hosts a demo and a rough schematic diagram — no installation required. Because the documentation is explicitly still being completed, budget time for cross-referencing the repository when a guide step is missing.