> ## Documentation Index > Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt > Use this file to discover all available pages before exploring further. # Build a Code Research Agent > Reference architecture and an example system prompt for building your own agent on top of the CodeAlive Tool API ## 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](/api-reference/toolapi/list-visible-data-sources) and the [MCP server](/integrations/mcp). 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. ## Architecture A code research agent is a loop: 1. The user asks a question about a codebase. 2. The LLM decides which tool to call and with what arguments. 3. Your runtime executes the call against the CodeAlive Tool API (or through MCP) and appends the result to the conversation. 4. 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. ```bash theme={null} 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](/api-reference/toolapi/list-visible-data-sources) 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. ```markdown title="system-prompt.md" theme={null} 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?"*: ```json theme={null} 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. ```json theme={null} 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. ```json theme={null} 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. ```json theme={null} 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. 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 `` 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`. ## Related resources Parameters and response examples for every tool Make off-the-shelf agents prefer CodeAlive tools Use the same tools through MCP instead of raw HTTP How CodeAlive's search works under the hood