Skip to main content
Version: v2.0

Build your first agent

This tutorial builds one agent from nothing to a committed version. Along the way you meet every part of an agent: its instructions, its tools, its skills, and its permissions. Each idea is explained where you first meet it, with a link to the full version.

What you are building​

An agent that reads merged pull requests from one GitHub repository and drafts release notes in your team's format.

ChatGPT gives you one prebuilt agent that already works for everything. Agenta gives you an empty one, so the first decision is what the agent is for. Everything you add below follows from that answer. See Agents.

Before you start​

  • An Agenta account. Agenta Cloud is the hosted version. To run Agenta yourself, see the self-host quick start.
  • An API key from a model provider. This tutorial uses OpenAI. For any other provider, see Choose a harness and model.
  • A GitHub account, and one repository with merged pull requests in it.

If you have never opened Agenta before, the quick start is a shorter run that needs no GitHub account.

Step 1: Describe the agent​

Open your project. The home screen asks What do you want to build?

Type the job:

Read the pull requests merged into one of my GitHub repositories and
draft release notes from them in my team's format.

Click Create agent. Agenta creates the agent, names it, and opens its playground.

Step 2: Connect a model​

The playground opens in Build mode. On the left is the Configuration column, which holds everything the agent is. On the right is the conversation.

An agent runs on two pieces. A model answers messages and does nothing else. A harness drives the model: it sends the conversation, runs the tools the model asks for, feeds the results back, and manages the context as the conversation grows. See Harnesses and models.

To connect a model:

  1. In the Configuration column, click Model & harness.
  2. Leave the segmented control on API key.
  3. Click the OpenAI tile.
  4. Paste your key into API key * and click Save.

With a key saved, the agent can run.

Step 3: Let the agent interview you​

The conversation opens with a card holding your description and a Start button. Click it.

The agent asks about the job: which repository, who reads the release notes, what they need to contain. Answer in plain sentences. Tell it the repository you want to use.

You are configuring the agent by talking to it. While you are in the playground, the agent carries a set of extra tools and skills called the playground build kit, which let it find tools, ask you to connect an app, and change its own configuration as you talk. You can see it under Advanced, where its status reads Removed on commit: none of it is part of the agent you publish.

Watch the Configuration column while you answer. Sections change as the agent works.

Step 4: Write the instructions​

The instructions are the agent's identity. Other tools call this the system prompt. In Agenta they live in a file called AGENTS.md, and they are the first thing sent to the agent at the start of every session.

They are also resent on every turn, so a long identity is a recurring cost rather than a one-time one. Keep them to what has to be true every time.

Open them and read what the agent wrote:

  1. In the Configuration column, click Instructions.
  2. Click the AGENTS.md row. The editor opens.
  3. Use Edit to write, Preview to see the rendered markdown, and Source in the toolbar to work in raw markdown.

Add the context only you have. For this agent, that is who reads the release notes and how they should sound. The examples below use acme/checkout; use your own repository throughout.

## Role

You draft release notes for the acme/checkout repository. They are read
by customer support, not by engineers.

## Style

Write one line per user-visible change, in plain sentences. Name what
changed for the person using the product, not the code that changed.
Skip internal refactors, dependency bumps, and test changes.

Click Save.

The right rail of the editor offers + Output format, + Tone & style and + Guardrails, which insert headings for you to fill in. For more on what to put under them, see Write your agent's instructions.

tip

Instructions grow one line at a time, against real failures. When the agent gets something wrong, add the line that would have prevented it.

Step 5: Give it a tool​

A tool is one action the agent can take. Tools are defined per action rather than per product: not "GitHub", but "list pull requests", "comment on a pull request", "create an issue". Each carries its own description, and the agent picks the ones that fit the task in front of it. See Tools and integrations.

Ask the agent for what it needs:

You need to read merged pull requests from acme/checkout on GitHub.
Find the tools for that and add them.

The agent looks for matching tools and asks you to connect GitHub. Complete the connection, and the tools appear in the Tools section of the Configuration column, grouped under CONNECTED APPS. New ones carry a green New badge, and the state dot in the header turns to Draft.

tip

You can also add a tool yourself. Click the + (Add tool) button on the Tools section and choose Third-party integration. The Add app tools dialog lets you search apps, pick a connected one, and choose actions from it. Actions that only read carry a READ-ONLY badge.

Every tool an agent has costs a little on every turn, because its name and description go to the model each time. Add the actions the job needs and leave the rest.

Step 6: Add a skill​

A skill is a short handbook for one kind of task. It sits outside the instructions, and the agent sees only its name and description until it decides the skill applies. Then it loads the body and follows it. That is why an agent can carry many skills and pay for almost none of them. See Skills.

Your release-notes format is exactly that shape: a procedure the agent needs sometimes, and too long to sit in the instructions.

  1. Click the + (Add skill) button on the Skills section. The New skill dialog opens.

  2. In Name, type release-notes.

  3. In Description, write when the agent should reach for it:

    Use when drafting release notes, a changelog entry, or a summary of what
    shipped. Covers the section order, the wording, and what to leave out.

  4. In the SKILL.md editor, write the procedure:

    # Release notes

    1. Group the merged pull requests into New, Improved, and Fixed.
    2. Write one line per change. Start with a verb. Name the feature the
       customer sees.
    3. Drop anything with no user-visible effect.
    4. Put a one-sentence summary of the release at the top.
    5. Save the result as a markdown file.

  5. Click Create.

The description decides whether the skill fires, because it is all the agent sees up front. Write it as a situation the agent can recognize, not as a summary of the contents.

The same dialog takes skills written elsewhere. Drop a skill folder, a .zip, or a .skill file onto Drag a skill folder, .zip, or .skill here, or use Browse files. See Manage skills.

Step 7: Set permissions​

Your agent can now read from GitHub and write files. Permissions decide which of those it does on its own, and which it stops to ask you about first. See Permissions.

  1. In the Configuration column, click Advanced.
  2. Open the Permissions section.
  3. Set Policy to Allow reads. It is the default, so it may already be selected.
  4. Click Save.

The four policies are:

PolicyWhat it does
Allow readsReads run, writes ask. This is the default.
Allow allEvery tool runs without asking.
AskA human approves every tool call.
Deny allEvery tool call is refused.

With Allow reads, the agent reads pull requests on its own and stops before it writes anything.

Step 8: Run it​

Start the job:

Draft release notes for the pull requests merged into acme/checkout in
the last two weeks. Save them as release-notes.md.

The agent calls the GitHub tool, loads the release-notes skill, and drafts the notes. When it reaches the point of writing the file, it stops. A card headed Approval needed to continue appears in the conversation, naming the tool it wants to use, with the arguments under Details.

Click Approve. The run continues, and the file appears in the conversation as a card with a Download button.

The card also carries a toggle to always allow that tool for this agent. Turning it on adds the tool to Auto-approve under Permissions, so it stops asking.

Under each of the agent's replies you can see the duration, the tokens, and the cost of that turn. See Cost and usage.

Step 9: Commit a version​

Everything you changed so far is a draft. The state dot next to the version pill reads Draft, and Commit is enabled.

  1. Click Commit.
  2. The left pane, What's changing, lists every section you touched.
  3. Keep New version selected. The right pane tells you which version it saves as, and that everyone using the agent gets your changes.
  4. Edit the Commit message if you want, then click Commit.

The version pill moves on and the state dot goes back to Saved. The playground build kit is not carried into the committed version, so what you published is the instructions, tools, skills, and permissions you gave it.

To see the history of an agent's configuration, open Registry in the agent's sidebar. It lists every variant and every version with the model, who created it, and the commit notes. See Sessions and versions.

What you built​

An agent with a job, instructions that describe it, one connected tool, one skill, a permission policy, and a version history. You built almost all of it by talking to it.

Next​