Skip to content
Source
Sign inSign up

Write your first agent

Software factory / Custom agents

Write your first custom agent

You want an agent that does one job the built-in agents do not do, for example label each new bug report. Write it in one TypeScript file, check it on your machine, save it, and see it run on a new issue.

3 min read

You need:

  • Admin access to the repository.
  • Node.js 22.12 or later, to check the file on your machine.
  • At least one built-in agent on. Custom agents run only then: see Turn on the agents.

1. Write the factory file

Save this file as house.ts:

import { defineFactory } from '@tanstack-source/ci'
import { forgeTools } from '@tanstack-source/ci/agent'
import { chat, defineAgent } from '@tanstack/ai'

export default defineFactory('house', {
  agents: {
    'label-bugs': {
      agent: defineAgent({
        name: 'label-bugs',
        description: 'Adds the bug label to new issues that report a bug.',
        run: (ctx) =>
          chat({
            adapter: ctx.forge!.model(),
            systemPrompts: [
              'You read one new issue of this repository.',
              'If it reports a bug, add the label "bug" with the label tool.',
              'Then record the verdict "bug" or "not-bug" with record_verdict.',
            ],
            tools: forgeTools(ctx, ['label', 'record_verdict']),
            messages: ctx.messages,
            ...ctx.forward,
          }),
      }),
      on: ['issue.opened'],
      trigger: { on: 'everyone' },
    },
  },
})

Each agent has two parts:

  • agent: a TanStack AI agent. Its run is your code. It can use any tool, MCP client or package of TanStack AI.
  • The forge fields next to it: on (the events that start it), trigger (who starts it), model and budget.

In run, ctx.forge connects your agent to the forge:

  • ctx.forge.model(): the model of the agent. The forge calls the model with the key. When the forge pays for the model, the cost of each call counts toward the monthly spend cap. The sandbox never gets the key.
  • forgeTools(ctx, [...]): the forge's tools, such as label, comment and record_verdict. The forge runs each call with the limits of the built-in agents.
  • ctx.messages: the first message, with the issue or pull request and its comments.

Note

An agent has no token limit unless you set one. To set one, add budget: { maxTokens: 100_000 } to the agent. The run stops after that many tokens. The monthly spend cap and the time limit of a run also stop an agent that runs too long.

2. Check the file on your machine

defineFactory checks the forge fields when the file runs. It throws an error that names the factory, the agent and the field. Run:

pnpm add -D @tanstack-source/ci @tanstack/ai
node --experimental-strip-types house.ts

If the file has a problem, the command prints the error and stops with exit code 1.

3. Save the file in the vault

  1. Open Agents, then go to Custom agents under Software factory.
  2. Type house in File name.
  3. Upload house.ts, or paste it in Contents.
  4. Click Save file.

Or with the CLI:

src factory upload-agent house house.ts
src factory agents

The file is encrypted in the vault, for admins only. After you save it, no page shows its contents again. A file name has lowercase letters, digits and dashes, up to 40.

After you save the file, the forge bundles it: the file and the packages that it imports become one JavaScript file. It can take a few seconds. Then the Custom agents card shows label-bugs under Loaded from the vault, with its file and its events.

4. See it run

Open a new issue. Its Factory panel gets a label-bugs row with its verdict, and the issue gets the bug label.

Done

Your agent runs with the same limits as the built-in agents, as the same bot, with no key and no token in its sandbox.

If the card shows an error, see Fix an error in the factory file. To give the agent an MCP server or an API key, see MCP servers and secrets.