LLM Agent Planner Prototype
artur-cesar/llm-agent-planner-prototype
Prototipo de planejador LLM com execução multi-step e persistência de contexto
Ver no GitHubProtótipo backend em NestJS para explorar arquiteturas de aplicações baseadas em LLM. Implementa um sistema de planejamento capaz de raciocínio multi-turno, chamada de ferramentas e execução sequencial de múltiplas tools em uma única requisição, mantendo contexto conversacional persistido.
Instalação
npx convez-ai artur-cesar/llm-agent-planner-prototype1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Desenvolvimento de sistemas de agentes autônomos com raciocínio
- Exploração de arquiteturas event-driven para chamada de ferramentas
- Prototipagem de assistentes com conversas multi-turno e context awareness
Veredito

Projeto de pesquisa bem estruturado que evolui concretamente uma abordagem anterior. Código limpo com foco em spec-driven development e validação prática de padrões de agent planning. Ideal para quem quer entender internals de sistemas LLM-based em produção.
README
A tradução para o português deste README ainda está na fila.
LLM Order Planner Prototype
🔎 Overview
This project is a backend prototype built with NestJS to explore LLM-based application architectures.
It evolves from a simple tool-calling system into a planner-based execution model capable of:
- multi-turn conversations
- tool calling
- multi-step reasoning
- sequential execution of multiple tools within a single user request
The system persists conversations and maintains context across requests using:
x-user-id(simulated authentication)conversationId(multi-turn continuity)
🧭 Spec-Driven Development With Codex
This project is developed using a spec-driven workflow.
Each feature is defined as a structured specification and then implemented step-by-step using Codex.
Key principles:
- break features into explicit tasks
- define acceptance criteria before coding
- implement in small, verifiable steps
- avoid premature abstraction
- keep architecture aligned with real problems
Specs live under the spec/ directory and guide the evolution of the system.
⚙️ Stack
- Node.js
- NestJS
- TypeScript
- PostgreSQL
- TypeORM
- Docker
- Anthropic (Claude) API
- Jest (testing)
- OpenAPI (Swagger)
▶️ How To Run
# install dependencies
npm install
# run database (docker)
docker-compose up -d
# run migrations (if needed)
npm run migration:run
# start app
npm run start:dev
🌐 Docs (OpenAPI + Swagger)
Once the app is running, access:
http://localhost:3000/docs
Swagger UI allows you to:
- explore the /ask endpoint
- test requests interactively
- understand request/response contracts
🧠 What The Code Does
At a high level:
- Receives a user prompt via /ask
- Persists the message in a conversation
- Builds full conversation context
- Delegates execution to a planner-based runtime
Execution flow:
AskService
-> TurnRunnerService
-> Planner (LLM-driven)
-> decides next action
-> ToolExecutorService
-> executes tools
-> loop until final answer
The system can:
- respond directly
- call one tool
- call multiple tools sequentially
- combine results into a final response
📬 API Definition
POST /ask
Request:
{
"prompt": "string",
"conversationId": "string (optional)"
}
Headers:
x-user-id: string
Response:
{
"content": "string",
"conversationId": "string"
}
📬 API Examples Direct answer
{
"prompt": "Explain agents in one sentence"
}
Single tool call
{
"prompt": "What is the status of order 123?"
}
Multi-tool execution (core feature)
{
"prompt": "What is the status and items of order 123?"
}
Expected behavior:
- system calls getOrderStatus
- system calls getOrderItems
- system returns a combined answer
Multi-turn conversation First request:
{
"prompt": "What is the status of my order?"
}
Response:
{
"content": "Which order?",
"conversationId": "abc-123"
}
Follow-up:
{
"prompt": "Order 123",
"conversationId": "abc-123"
}
📦 Previous Prototype
This project builds on:
👉 https://github.com/artur-cesar/tool-caller-prototype
The previous system:
- supported tool calling
- but only allowed:
- 0 tool calls (direct answer)
- 1 tool call per turn
Limitation:
User: "status AND items of order 123"
→ system could not execute both tools in the same turn
🚀 What This Prototype Solves
This version introduces a planner-based execution loop that enables:
- multiple tool calls in the same turn
- step-by-step reasoning
- result composition across tools
In short:
Before:
LLM → 0 or 1 tool → response
Now:
LLM → tool → LLM → tool → LLM → response
🧠 Why This Matters
This is the foundation for:
- planner-based agents
- autonomous workflows
- real-world LLM orchestration systems
The architecture is intentionally simple, explicit, and extensible.