InfraStudio Agents Start free

Guides

Custom agents, orchestrations and webhooks

Write an agent of your own in plain words, chain agents into an orchestration, start it after another agent finishes, and start either one from another system with a webhook.

Last updated

After this guide, you have an agent that does a job you described yourself, a chain of agents that starts with one press, and a way for another system to start them.

Three ideas come up:

  • A custom agent is an agent you write yourself: a name and instructions in plain words.
  • An orchestration is a chain of agents with one start. A step starts after the one before it is done, or side by side with it.
  • A webhook is an address that another system calls, with a key, to start an agent or an orchestration.

Write a custom agent

  1. Open Agents in the menu.
  2. Next to the product's name, press New custom agent.
  3. Give it a name, and write its Instructions: what it should look at, and what a good answer is. For example: "Read the pull requests merged this week and write release notes for customers."
  4. Choose a schedule under Schedule (optional), or leave No schedule. Your own schedule takes a rule of five fields. An agent may start at most once an hour.
  5. Press Save.

A custom agent reads the same things as a question in Chat: your code, the reports, your suggestions, and the tools you connected, such as your analytics. It changes nothing. When it finds a change worth making, it can make up to five suggestions, and each one waits for your yes in Suggestions, like any other.

Note

A product can have up to 20 custom agents. Instructions can be up to 8,000 characters.

What you see when it worked

The agent is in the list on the Agents page. Press Start now to try it once. You can write Words to start with (optional), and the agent gets them as part of what it should do. When the job is done, the product's news says so, and Last answers on the agent's row shows what it wrote. The newest five answers are shown.

Edit changes the name, the instructions and the schedule. Delete removes the agent and its answers. An agent that is a step of an orchestration can't be deleted until you take it out of there.

Chain agents into an orchestration

Open Orchestrations in the menu, with the product picked at the top of the side bar.

The first part of the page, How the agents work together, is a map of the ready-made agents: what happens on GitHub, which agent starts then, and where your yes is needed. Agents that are off are dimmed. The box You get the news names where the product's news goes when an agent's job ends: Telegram, Slack, or the website when neither is linked. You can say your yes in the same places. The order of the boxes is fixed: it shows how the work flows.

You can change an agent from the map. Click its box, or move to it with the Tab key and press Enter. A small window opens with Starts by itself, the agent's Schedule when it works on one, and its options. Press Save. The map is drawn again, and an agent you turned off is dimmed. Auto-merge is the exception: it is changed in Product settings, where its checks are listed.

To make a chain of your own:

  1. Press New orchestration.
  2. Give it a name, and choose a schedule if it should start by itself.
  3. Under Steps, pick an agent for the first step. Press Add a step for each next one.
  4. For each step, choose what it Comes after: The start, or an earlier step. Two steps that come after the same one work side by side.
  5. A step is skipped when the step before it failed. Tick Start it even if the step before failed to start it anyway.
  6. Look at the picture under How it will look, and press Save.

Start it after an agent finishes

An orchestration can start by itself each time one of your agents finishes a job. For example: the Product analytics review ends, and a custom agent writes a short summary of it for your team.

  1. In the orchestration's form, find Also start it after an agent finishes and pick the agent.
  2. Tick Also when that job failed if it should start then too. A job that someone stopped starts nothing.
  3. Press Save.

The first steps read what that agent wrote, when they are custom agents. They read it as material to work on, never as instructions.

On the map, the orchestration is now a box with a dashed border after its agent. Click it to go to the orchestration. In History, such a start says After an agent finished.

A few rules keep this safe:

  • Each job of the agent starts the orchestration once. Jobs that ended before you chose the agent start nothing.
  • The agent can't be one of the orchestration's own steps, and it can't be Mentions or Auto-merge.
  • A job that an orchestration started as a step never starts another orchestration. So two orchestrations can't start each other in a circle.
  • While the orchestration is still working, a new job of the agent starts nothing.
Note

An agent that works often, such as PR reviewer, starts the orchestration after each of its jobs. Each step is a job of your plan.

A step can be a custom agent, or a ready-made agent that works on a schedule, such as Docs updater or Product analytics review. An agent that answers GitHub, such as PR reviewer, can't be a step: it needs a pull request or an issue to work on.

A custom agent that comes after another step reads what that step wrote. It reads it as material to work on, never as instructions. A ready-made agent does not read the step before it.

Note

An orchestration has at most 10 steps, and a product at most 20 orchestrations. Each step is a job, and counts toward your monthly plan, if it has a limit.

Start it, follow it, stop it

Each orchestration under Your orchestrations shows its steps as a picture. The picture ends with You get the news: each step's job tells you how it went, in the same places. Press Start now to start it by hand. It also starts on its schedule, by its webhook, and after an agent finishes, while it is on. An orchestration that is off still starts when you press Start now.

While it works, each step's box shows how it is going, and the page keeps itself up to date. One orchestration works on one start at a time: a second start is refused until the first one is over.

History lists the last starts. Pick one to see each step: how it went, when, the job on the Activity page, and What it wrote for a custom agent.

Stop it stops the step that is working and starts no more steps.

Start an agent or an orchestration with a webhook

Another system can start an agent or an orchestration: your deploy tool when a release is out, your monitoring when an alert fires, or a form on your site.

  1. On the Agents page, open Webhook under the agent. For an orchestration, open Webhook on its card.
  2. Press Make a webhook key.
  3. Copy the key. It is shown once. If you lose it, make a new one. Then tick I saved the key.
  4. In the other system, send a call to the address, with the key:
curl -X POST https://infrastudio.io/api/agent-hook \
  -H "Authorization: Bearer <your webhook key>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Release 42 is out"}'

The answer 202 means the call is taken, and the agent starts shortly.

What you send is given to a custom agent as material to work on. It is never treated as instructions, so a call can't make the agent do something its instructions don't ask for. A ready-made agent reads nothing of what you send. An agent that works on one pull request or issue, such as PR reviewer, needs its number: send {"number": 12}.

A webhook starts only the agent or the orchestration it was made for, and only while that is on. Make a new key replaces the key at once, and the old key stops working. Turn off removes the webhook.

Warning

Anyone who has the key can start the agent, and each start uses your AI account. Keep the key where you keep passwords, and make a new one when a person who knew it leaves.

Limits

  • A key takes up to 100 calls a day.
  • One call can carry up to 32 KB. The agent reads the first 8,000 characters.
  • To make sure a repeated call starts nothing twice, send an Idempotency-Key header with a value of your own, for example the release's number. A second call with the same value gets the answer 200 and starts nothing.
  • When your plan's jobs for the month are used up, a call gets the answer 429 and starts nothing.
AnswerWhat it means
202The call is taken.
200The same call was taken before (the same Idempotency-Key).
401The key is missing, wrong, or no longer in use.
409The agent or the orchestration is off.
413The call is larger than 32 KB.
429Too many calls today, or the month's jobs are used up.

More