Build a Code Research Agent

Overview

CodeAlive’s own chat is powered by an internal research agent that runs an LLM loop over the same tools exposed publicly as the Tool API and the MCP server. This guide shows how to build a similar agent yourself: which tools to give it, how to instruct it, and what a complete research loop looks like. The system prompt below is an adapted, self-contained version of the strategy CodeAlive uses in production. Copy it as a starting point and tune it for your stack.

Looking for more patterns and practical ideas for building AI agents? Explore the CodeAlive blog.

Architecture

A code research agent is a loop:

The user asks a question about a codebase.
The LLM decides which tool to call and with what arguments.
Your runtime executes the call against the CodeAlive Tool API (or through MCP) and appends the result to the conversation.
Steps 2–3 repeat until the LLM has enough evidence, then it writes the final answer.

Every Tool API operation is read-only and returns the same envelope: obj (structured JSON) and rendered (agent-friendly text). For an agent loop, request output_format: "agentic" and feed rendered straight into the model — it is compact and already carries follow-up hints.

curl -X POST https://app.codealive.ai/api/tools/semantic_search \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How does task execution work?",
    "data_sources": ["agent-framework"],
    "output_format": "agentic"
  }'

Which tools to give the agent

Expose all eleven tools; each covers a distinct move in the research loop:

Tool	Role in the loop
`get_data_sources`	Discover repository and workspace names. Call once at session start.
`get_repository_ontology`	Orient: high-level map of one repository before focused search.
`get_file_tree`	Orient: bounded directory structure with summaries.
`semantic_search`	Locate by meaning: default first tool for behaviour and architecture questions.
`grep_search`	Locate by text: exact names, literals, error strings, acronyms, exhaustive sweeps.
`fetch_artifacts`	Read: preferred reader for known artifact identifiers.
`get_artifact_relationships`	Traverse: callers, callees, inheritance, references of a known artifact.
`read_file`	Read: fallback for exact paths without an artifact identifier; bound with `start_line`/`end_line`.
`get_artifact_query_schema`	Analytics: the ArtifactQuery DSL catalog.
`query_artifact_metadata`	Analytics: repository-level metrics (languages, lines, complexity, public API surface).
`chat`	Delegate: a full end-to-end answer from CodeAlive’s own agent. Use sparingly — it is the most expensive tool, and you are already running your own loop.

The generated API Reference documents parameters, request examples, and response shapes for each tool.

Example system prompt

This prompt distills the search strategy CodeAlive’s production agent uses. It assumes the eleven tools above are bound with their canonical names.

system-prompt.md

You are a code research assistant. You answer questions about the user's
codebases by calling CodeAlive tools to gather evidence, then answering the way
a senior developer would.

## Tool strategy

Iterate: orient → locate → traverse → read. Combine tools; do not try to solve
everything in one call.

1. Call `get_data_sources` once to learn which repositories are available. Use
   the returned `name` values in every `data_sources` / `data_source` argument.
2. For an unfamiliar repository, orient first: `get_repository_ontology` (one
   repository per call) or a bounded `get_file_tree`.
3. Locate code with the search tool that matches the query shape:
   - Concept, behaviour, mechanism, or architecture question → `semantic_search`.
   - Exact symbol name, string literal, error text, route, config key, or an
     "all usages" sweep → `grep_search`.
4. Traverse from a found artifact with `get_artifact_relationships`: callers and
   callees (`calls_only`), base types and implementations (`inheritance_only`),
   or where-used (`references_only`).
5. Read code with `fetch_artifacts` for every identifier you rely on. Use
   `read_file` only for exact paths that no tool has returned an identifier
   for, and bound it with `start_line`/`end_line`.

## Query phrasing rules

- Phrase `semantic_search` questions as full natural-language English sentences:
  "How does request deduplication work?", "Where is retry handling implemented?"
  Never pass bare keywords ("auth", "payment processing") — keyword strings
  sharply degrade recall. Keep user-named identifiers and codebase terms
  verbatim inside the sentence.
- Acronyms and rare short tokens (JWT, OIDC, OTel) are underrepresented in
  embeddings: when the user names one, run `grep_search` on the exact token in
  addition to `semantic_search`, not instead of it.
- For multi-faceted questions, issue several `semantic_search` calls with
  distinct angles (entry point, transport, storage, consumers) rather than one
  bundled query.

## Evidence rules

- Code is the source of truth. Treat READMEs and docs as orientation, not proof
  of current behaviour; verify doc claims in implementation, config, or tests
  before stating them as fact.
- Never make factual claims from search-result snippets alone — fetch and read
  the artifact first.
- For "how does X work?" questions, verify the full flow before answering:
  the upstream entry point (HTTP route, job, event handler), the mechanism
  core, and the storage or side effect. An internal helper is the mechanism
  core, not the whole flow — find who calls it.
- Empty or weak results mean the query was too narrow, not that the answer
  does not exist. Try at least two distinct strategies (synonyms, a different
  abstraction level, the other search tool) before saying "not found".
- Stop searching when the evidence is sufficient. Do not run speculative
  extra searches once the entry point and mechanism core are verified.

## Answering

- Support key conclusions with short exact code snippets, plus file path and
  symbol name.
- State assumptions explicitly. If two interpretations of the question lead to
  materially different answers and no tool call can discriminate, ask one
  focused clarifying question with concrete options instead of guessing.
- If evidence is incomplete after several attempts, say what you searched for
  and what remains unverified.

The production prompt additionally handles multi-turn conversation state, workspace-scale scoping (up to ~1,000 repositories per workspace), and structured research-completion checkpoints. Those concerns are specific to CodeAlive’s harness — start with the version above and add orchestration rules as your agent grows.

Worked example

A typical run for “How does task execution work in agent-framework?”:

Discover data sources

POST /api/tools/get_data_sources
{ "query": "task execution framework" }

The response lists agent-framework as a ready repository — its name goes into every following call.

Search by meaning

POST /api/tools/semantic_search
{
  "question": "How does task execution work, from scheduling to completion?",
  "data_sources": ["agent-framework"]
}

Top hit: CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run — a method artifact with a relevance score and a one-line description.

Read the core

POST /api/tools/fetch_artifacts
{ "identifiers": ["CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run"] }

The artifact content shows retry and telemetry wrappers — this is the mechanism core, but not the entry point.

Find the entry point

POST /api/tools/get_artifact_relationships
{
  "identifier": "CodeAlive-AI/agent-framework::src/executor.py::TaskExecutor.run",
  "profile": "calls_only"
}

Incoming calls reveal Scheduler.tick in src/scheduler.py — the upstream trigger that drains the queue.

Answer with evidence

The agent now has the full flow — entry point (Scheduler.tick), mechanism core (TaskExecutor.run), and side effects — and answers with file paths and short snippets.

Practical notes

Rate of tool calls. Search tools are billed per call (see x-codealive-billing in the OpenAPI spec); read and traversal tools (fetch_artifacts, get_artifact_relationships, read_file, get_file_tree) are not. Structure the loop to search once and read many.
Repairable errors. Invalid arguments come back as HTTP 200 with obj.error = { code, message, retry, try } and a rendered <tool_error> block. Feed the error to the model — the try hint is written so an LLM can repair the call and retry.
Stateless chat. If you do expose chat, remember every call is independent: prior findings and identifiers must be repeated inside question.

API Reference

Parameters and response examples for every tool

Instructing Coding Agents

Make off-the-shelf agents prefer CodeAlive tools

MCP Overview

Use the same tools through MCP instead of raw HTTP

Semantic Search

How CodeAlive’s search works under the hood

Getting Started

Features

Model Context Protocol

Agent Skills & Plugins

Instructing Agents

Build a Code Research Agent

Overview

Architecture

Which tools to give the agent

Example system prompt

Worked example

Practical notes

API Reference

Instructing Coding Agents

MCP Overview

Semantic Search

​Overview

​Architecture

​Which tools to give the agent

​Example system prompt

​Worked example

​Practical notes

​Related resources

API Reference

Instructing Coding Agents

MCP Overview

Semantic Search

Overview

Architecture

Which tools to give the agent

Example system prompt

Worked example

Practical notes

Related resources