Guided walkthrough

Build an agent that takes a search query and returns up to three links. You’ll test it with sample data, deploy it to Sapiom, then run a real web search and inspect the result.

Use Agent Studio or Claude Code or Codex throughout. The code and prompts below work with either setup.

Start with your hello-world project

Open the hello-sapiom project from the quickstart. If you’re starting here, complete Set up your project first. You’ll need your Sapiom account connected and your coding-agent session open in that folder.

An agent project is a folder of TypeScript files. Its index.ts defines what the agent accepts, what each step does, and when the run finishes. You’ll replace the greeting with a search while keeping the rest of the project.

1. Add a search step

Ask your coding agent to replace index.ts with the code below and check the project. You can also edit the file yourself in Studio’s Code view or your editor.

import { defineAgent, defineStep, terminate } from "@sapiom/agent";
import { z } from "zod/v4";

const search = defineStep({
  name: "search",
  inputSchema: z.object({
    query: z.string().min(1).default("Astro documentation"),
  }),
  next: [],
  terminal: true,
  async run(input, ctx) {
    const response = await ctx.sapiom.search.webSearch({
      query: input.query,
      intent: "links",
    });

    return terminate({
      query: input.query,
      results: response.results.slice(0, 3).map(({ title, url }) => ({
        title,
        url,
      })),
    });
  },
});

export const agent = defineAgent({
  name: "hello-sapiom",
  entry: "search",
  steps: { search },
});

There are three parts to this agent:

Input: query is a nonempty string. Its default lets you run the agent without entering anything.
Work: ctx.sapiom.search.webSearch finds pages. intent: "links" asks for search results. The step keeps the first three titles and URLs.
Result: terminate(...) finishes the run and returns the result. This agent needs only one step.

Sapiom supplies the search connection when the agent runs in the cloud; you don’t need a separate search-provider API key.

2. Test with a known result

Local Run uses test data for Sapiom capabilities. Your step code runs, but the search returns a supplied response instead of searching the web. That gives you a repeatable way to check the output before making a live call.

Ask your coding agent to save this response in .sapiom-dev/stubs.json:

{
  "version": 1,
  "steps": {
    "search": {
      "search.webSearch": {
        "query": "Astro documentation",
        "results": [
          {
            "title": "Astro documentation",
            "url": "https://docs.astro.build/",
            "snippet": "Learn how to build a site with Astro."
          }
        ]
      }
    }
  }
}

The outer search names your step. search.webSearch names the capability whose response you’re replacing.

In your coding-agent session, paste:

Check this project, then run it locally with empty input {} and the stubs
from .sapiom-dev/stubs.json. Show the final output and confirm that the run
completed with no unused stubs or stub warnings.

The final output should be:

{
  "query": "Astro documentation",
  "results": [
    {
      "title": "Astro documentation",
      "url": "https://docs.astro.build/"
    }
  ]
}

The default query was applied, the search response reached your step, and the output contains just the title and URL you selected.

Try the empty-result case too: change the stub’s results to [] and run it again. The agent should complete with an empty results array. Restore the sample result when you’re done. See Test locally for more test options.

3. Deploy the agent

Deploying uploads your project and builds a version that Sapiom can run in the cloud. Further local edits take effect after you deploy again.

Deployment also requires a Git repository with at least one commit. In this tutorial project, ask your coding agent:

Check the project and rerun its local test. Confirm which Sapiom organization
I am signed in to. If this project is not a Git repository, initialize it.
If it has no commits, create an initial commit of the project files, excluding
credentials and installed dependencies. Link the project to a cloud agent,
creating that agent if needed, then deploy it. Wait for the build to be ready.

Continue when the build status is ready. A build still in progress or a failed build cannot serve your first run. If deployment fails, ask your coding agent to read the build error, fix it, and deploy again. The deployment guide has additional troubleshooting.

4. Run a real search

In the same session, paste:

Run the deployed agent in production with
{"query": "Astro documentation"}.
Return the execution ID, wait for the run to finish, and show its final output.

This time the search calls the real service. The local stub file is not used. Expect your query and up to three titles and URLs; the links can differ from the local test and from one run to the next. An empty results array is also a valid response.

The execution ID identifies this particular run. Starting a run is only the first part: wait for it to finish before checking its result.

5. Inspect what happened

Open the Agents dashboard, select your agent, and open its latest run. Or ask in your current session:

Inspect the run we just started. Show the search step's input and output,
its status, and any recorded search activity or error.

Check that the run completed, that the search step received your query, and that its output contains the returned links. If it failed, read the step’s error before trying again.

You now have a deployed agent that accepts input, uses a Sapiom capability, and returns a result you can inspect. Change the query for another run, or edit the code and redeploy to change its behavior.

Keep building

Read the Search guide to get a synthesized answer or broaden a query. Browse other capabilities when your agent needs to do more.

Run on a schedule Turn your deployed agent into a recurring task.