Building Agents

An agent is a single AI worker that follows a set of instructions you define. Each agent has its own prompt, language model, and optional tools and variables. Agents are the core building blocks of your automations in Obi.

Creating an Agent

1. Open an app from the sidebar.
2. Select Agents.
3. Click Create Agent.
4. Obi creates the agent with a default name and prompt. You can edit both immediately.

Configuring the Prompt

The prompt is the set of instructions that tells the agent how to behave. It determines what the agent does when it runs.

1. Select the agent from the list.
2. The prompt editor appears on the left side of the screen.
3. Write your instructions using plain text or Markdown. Be specific about what the agent should accomplish, what format to use for its output, and any constraints it should follow.
4. Changes save automatically as you type.

Good prompts are clear and direct. For example, instead of "handle emails," write "Read the incoming email, identify the sender's question, and draft a concise reply that answers the question directly."

Using Variables in Prompts

You can insert dynamic information into your prompts by referencing variables. When the agent runs, these variables are automatically replaced with actual values from the execution context.

To add a variable to your prompt:

1. Type {{ in the prompt editor.
2. An autocomplete menu appears showing available variable types.
3. Select the variable type you need from the list.
4. Complete the variable reference with the closing }}.

The available variable types include:

• trigger - Information from the event that started the execution (such as an incoming email or API request).
• project - Details about the project associated with this execution.
• execution - Current execution details like the execution ID.
• user - Information about the user who triggered the execution.
• memory - Access to saved information from your workspace memory store.

For example, if your agent processes incoming messages, you might write: "Analyze this message: {{trigger.message}} and respond to the sender at {{trigger.email}}."

When the execution runs, the agent receives the actual message content and email address instead of the placeholder text.

Using Variables in Prompts

You can insert dynamic data into your prompts using variables. Variables let you reference information that changes with each execution, such as details from a trigger, workspace memories, or project context.

Writing Variable References

To reference a variable in your prompt, type two opening curly braces {{. Obi displays a list of available variables you can insert. Select one to add it to your prompt.

For example, if your agent receives an email trigger, you can write:

Summarize the following email: {{ trigger.email.body }}

When the agent runs, Obi replaces {{ trigger.email.body }} with the actual email content.

Available Variable Types

Obi provides several types of variables you can use in prompts:

• Trigger variables contain information from the event that started the execution, such as email content or API request data.
• Project variables give agents access to repository context, including code files and project instructions.
• Execution variables include details about the current run, such as the execution ID or timestamp.
• User variables reference information about the person who started the execution or the workspace owner.
• Memory variables let you read values stored in workspace memories during previous executions.

The autocomplete menu shows which variables are available based on your squad's configuration and connected integrations.

When to Use Prompt Variables

Use prompt variables when you need to pass specific pieces of information directly into your agent's instructions. This is different from input variables, which define structured data passed between agents in a squad.

Prompt variables work best for:

• Including the content of a trigger (like an email body or webhook payload) in your instructions.
• Referencing stored values from workspace memories.
• Inserting project-specific context, such as coding standards or repository details.

If your agent needs to receive data from another agent in the squad, use input variables instead. Prompt variables focus on embedding external or stored information into the prompt itself.

Choosing a Model

Each agent uses a language model to process its instructions and generate responses.

1. In the agent's configuration panel on the right, find the Engine dropdown.
2. Select an engine type (such as text or vision).
3. Below the engine, find the Model dropdown. Models are grouped by family.
4. Select the model you want to use.

The engine and model must be compatible. Obi validates the pairing and only shows models that work with your selected engine.

Adding Tools

Tools give agents the ability to interact with external services during execution. For example, a tool might let an agent search the web, read files from GitHub, or create issues in Linear.

Before you can add tools to an agent, the corresponding integration must be connected in your workspace settings.

1. In the agent's configuration panel, find the Tools section.
2. Click the Add Tool dropdown.
3. Browse or search the available tools. These come from your connected integrations.
4. Select a tool to attach it to the agent.

You can remove a tool at any time by clicking the remove option next to it in the tools list. An agent can have multiple tools attached.

Defining Variables

Variables define what information flows into and out of an agent. They let you pass data between agents in a squad.

Input Variables

Input variables are values the agent receives when it runs. These might come from a trigger, a previous agent in the squad, or a user-provided value.

1. In the configuration panel, find Input Variables.
2. Click Add Variable or create a new one.
3. Give the variable a key (name) and select its type.

Output Variables

Output variables are values the agent produces after it finishes. These can be passed to the next agent in a squad or included in the final execution results.

1. In the configuration panel, find Output Variables.
2. Add a variable with a key and type.

Variable Types

Obi supports several variable types:

• String for text values.
• Number for numeric values.
• Boolean for true/false values.
• Enum for a fixed set of choices.
• Conversation for multi-turn chat history.
• Memory for references to persistent workspace memories.

Variables can also have constraints such as minimum or maximum values, regular expression patterns, or a list of allowed enum values.

Deleting an Agent

1. Select the agent from the list.
2. Use the delete option.
3. Confirm the deletion.

Deleting an agent removes it from any squads that reference it. Make sure the agent is not part of an active workflow before deleting.