{"id":26862107,"url":"https://github.com/eliyahougabbay/agentic-app-template","last_synced_at":"2026-05-06T22:09:44.960Z","repository":{"id":285159348,"uuid":"957240784","full_name":"eliyahougabbay/agentic-app-template","owner":"eliyahougabbay","description":"Production-ready template for building agentic apps with FastAPI, Pydantic AI, PostgreSQL, and full tracing via Jaeger.","archived":false,"fork":false,"pushed_at":"2025-03-29T22:07:57.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T23:19:27.318Z","etag":null,"topics":["agentic-app","ai-agents","async","azure-openai","docker","fastapi","jaeger","pydantic-ai","template"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eliyahougabbay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-29T22:04:28.000Z","updated_at":"2025-03-29T22:14:43.000Z","dependencies_parsed_at":"2025-03-29T23:29:30.436Z","dependency_job_id":null,"html_url":"https://github.com/eliyahougabbay/agentic-app-template","commit_stats":null,"previous_names":["eliyahougabbay/agentic-app-template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliyahougabbay%2Fagentic-app-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliyahougabbay%2Fagentic-app-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliyahougabbay%2Fagentic-app-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliyahougabbay%2Fagentic-app-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eliyahougabbay","download_url":"https://codeload.github.com/eliyahougabbay/agentic-app-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246404420,"owners_count":20771607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-app","ai-agents","async","azure-openai","docker","fastapi","jaeger","pydantic-ai","template"],"created_at":"2025-03-31T02:23:10.934Z","updated_at":"2026-05-06T22:09:39.922Z","avatar_url":"https://github.com/eliyahougabbay.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 Agent Template\n\nA minimal, production-ready template for building **agentic applications** using [Pydantic AI](https://github.com/pydantic/pydantic-ai), with clean async architecture and full observability.\n\nThis template runs on:\n\n- **FastAPI** – for async APIs and agent serving\n- **Pydantic AI** – to structure agents, tools, and usage limits\n- **PostgreSQL** – to persist conversations and data\n- **Jaeger** – for distributed tracing (via OpenTelemetry)\n- **Docker Compose** – to run everything locally\n\n\n## ⚙️ Stack Overview\n\n| Component   | Purpose                                                       |\n|-------------|---------------------------------------------------------------|\n| FastAPI     | Exposes the `/run-agent` and `/webhook` endpoints             |\n| Pydantic AI | Agent framework with usage tracking                           |\n| PostgreSQL  | Persists conversations and other data                         |\n| Jaeger      | Debug and trace agents via distributed tracing                |\n| Alembic     | Manages database migrations                                   |\n\n\n## 🧩 Features\n\n- Agent-first architecture powered by [Pydantic AI](https://github.com/pydantic/pydantic-ai):\n  - Structured agent workflows with type-safe inputs/outputs\n  - Built-in tool registration using `@agent.tool`\n  - Request-level usage limits (e.g., max 5 LLM calls per run)\n- Fully async, built on FastAPI\n- Webhook support for delivering results externally\n- Built-in tracing via Jaeger and OpenTelemetry\n\n\n## 🚀 Getting Started\n\n### 1. Create the `.env` file\n\nAt the root of the project, create a `.env` file and fill in your Azure OpenAI credentials:\n\n```dotenv\nAZURE_API_KEY=\nAZURE_ENDPOINT=\nAZURE_API_VERSION=\nAZURE_MODEL_ID=\n```\n\n### 2. Start the application\n\nRun the following command to build and start the application:\n\n```bash\ndocker-compose up --build\n```\n\nThis will start the following services:\n- web (FastAPI server)\n- postgres\n- pgAdmin (PostgreSQL GUI)\n- jaeger (tracing UI)\n\n### 3. Access the Services\n\n| Service      | URL                            |\n|--------------|---------------------------------|\n| API docs     | [http://localhost:8000/docs](http://localhost:8000/docs)     |\n| pgAdmin      | [http://localhost:5050](http://localhost:5050)          |\n| Jaeger       | [http://localhost:16686](http://localhost:16686)         |\n\n\u003e 🧠 pgAdmin login: `admin@example.com` / `admin`\n\n### 4. Develop Inside the Container\n\nTo run shell commands inside the `web` container:\n\n```bash\ndocker-compose exec web /bin/bash\n```\n\n### 5. Using the Template Effectively\n\n- **Database migrations** with Alembic:\n  ```bash\n  alembic revision --autogenerate -m \"your message\"\n  alembic upgrade head\n  ```\n- **Custom agent tools** can be added in `src/agents/` using the `@agent.tool` decorator.\n- **Tracing** is enabled automatically via `logfire` and exported to Jaeger.\n  You can view traces at [http://localhost:16686](http://localhost:16686).\n- **Code linting \u0026 formatting:** I recommend using [Ruff](https://docs.astral.sh/ruff/) for fast linting and formatting during development.\n\nThis gives you an interactive shell inside your running app.  \nUseful for debugging, running migrations, or launching ad-hoc scripts.\n\n\u003e ✅ The app uses `watchdog` to auto-reload on code changes inside the container.\n\n\n## 🧪 Example API Usage\n\nThis template is currently designed as an API-first setup — you interact with the agent by sending HTTP requests to the FastAPI backend.\n\n```bash\ncurl -X POST http://localhost:8000/run-agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"How do I start a company in France?\",\n    \"callback_url\": \"http://localhost:8000/webhook\"\n  }'\n```\n\n\n## 📂 Project Structure\n\n```text\n.\n├── Dockerfile\n├── docker-compose.yaml\n├── entrypoint.sh\n├── pyproject.toml\n├── requirements.txt\n├── alembic/\n├── src/\n│   ├── main.py\n│   ├── config.py\n│   ├── agents/\n│   ├── api/\n│   ├── db/\n│   ├── models/\n│   ├── schemas/\n│   └── services/\n```\n\n## 🔮 What's Next?\n\nThis template is designed to grow with you. In the future, you can easily add:\n\n- A task queue with [Dramatiq](https://dramatiq.io/) for background workflows\n- Redis (for caching or as a broker)\n- Multi-agent routing and tool chaining\n- JWT authentication or session management\n- Admin dashboard or logs viewer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feliyahougabbay%2Fagentic-app-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feliyahougabbay%2Fagentic-app-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feliyahougabbay%2Fagentic-app-template/lists"}