feat(kaapi): Implement agent initialization

[Ayush8923]

Issue

Closes #1210

Summary

a POST /agent endpoint, a read-only, natural-language Q&A agent over a project own Kaapi data (eval runs/datasets for text/STT/TTS, config versions, knowledge-base collections, documents). Ask a plain-English question about your project's evaluation data, get an answer, powered by Claude.

Architecture, LangGraph tool-use loop (graph.py):
A 2-node state machine: START → agent_node → (tool requested? → tool_executor_node → agent_node : END).

• agent_node calls Claude (configurable model, default claude-opus-5) with the system prompt + tool defs.
• tool_executor_node runs all requested tool calls concurrently.
• Capped at AGENT_MAX_ITERATIONS (default 8) rounds, after that, tool_choice is forced to "none" so the model must answer with what it has (stop_reason="iteration_limit").

Checklist

Before submitting a pull request, please ensure that you mark these task.

• Ran fastapi run --reload app/main.py or docker compose up in the repository root and test.
• If you've fixed a bug or added code that is tested and has test cases.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• ready-for-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: ProjectTech4DevAI/kaapi-backend/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: e1bf2b88-7c90-4692-b4d8-63878f465abb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

OpenAPI changes   🟢 1 non-breaking change

Tip

Safe to merge from an API-contract perspective.

Full changelog  ·  1

	Method	Path	Change
🟢	POST	/api/v1/agent	endpoint added

_{main ↔ 0e09ae49 · generated by oasdiff}

[codecov]

Codecov Report

❌ Patch coverage is 99.80720% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
backend/app/services/agent/executor.py	98.54%	2 Missing ⚠️
backend/app/tests/services/agent/test_executor.py	99.64%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Ayush8923]

we won’t merge this PR yet, as this is currently an experimental PR.

we are exploring OCS (Open Chat Studio) to understand how it can fit into Kaapi’s use cases. for now, we have implemented a simple route that answers our query, while the tools and other configurations are kept static using langraph.

Next action: #1230