{"id":42598250,"url":"https://github.com/agentsystems/agent-template","last_synced_at":"2026-01-29T00:13:29.157Z","repository":{"id":322053390,"uuid":"1080111891","full_name":"agentsystems/agent-template","owner":"agentsystems","description":"Starter template for building AI Agents compatible with AgentSystems","archived":false,"fork":false,"pushed_at":"2025-11-02T09:14:36.000Z","size":70,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-02T11:18:33.645Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://agentsystems.ai","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentsystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-20T22:14:50.000Z","updated_at":"2025-11-02T09:17:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentsystems/agent-template","commit_stats":null,"previous_names":["agentsystems/agent-template"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/agentsystems/agent-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagent-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagent-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagent-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagent-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentsystems","download_url":"https://codeload.github.com/agentsystems/agent-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagent-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28857227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T22:56:21.783Z","status":"ssl_error","status_checked_at":"2026-01-28T22:56:00.861Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-29T00:13:28.573Z","updated_at":"2026-01-29T00:13:29.149Z","avatar_url":"https://github.com/agentsystems.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Template\n\n[![GitHub stars](https://img.shields.io/github/stars/agentsystems/agentsystems?style=flat-square\u0026logo=github)](https://github.com/agentsystems/agentsystems/stargazers)\n\n\u003e [!NOTE]\n\u003e **Pre-Release Software** - AgentSystems is in active development. Join our [Discord](https://discord.com/invite/JsxDxQ5zfV) for updates and early access.\n\u003e ⭐ [**Star the main repository**](https://github.com/agentsystems/agentsystems) to show your support!\n\n\u003e This is the **reference agent template** for AgentSystems. See the [main repository](https://github.com/agentsystems/agentsystems) for platform overview and documentation.\n\nA minimal starter for building containerized AI agents that plug into the [Agent Systems](https://github.com/agentsystems) platform.\n\n*   Built on FastAPI + LangChain + LangGraph\n*   Uses OCI standard labels for container metadata\n*   No version tags or Docker image are published here – **this repo is a template**, not a distributable agent\n\n\nThe **Agent Template** is a minimal, batteries-included starter repo for building container-ised AI agents that plug into the [Agent Control Plane](https://github.com/agentsystems/agent-control-plane).\n\nThis repo is intended to be used via GitHub’s **“Use this template”** button or the `gh repo create` CLI. It can also be cloned directly for experiments.\n\n---\n\n## What you get\n\n| Path / file | Purpose |\n|-------------|---------|\n| `main.py` | FastAPI app exposing `/invoke` and `/health` endpoints. Contains an `invoke()` function you can customize. |\n| `Dockerfile` | Multi-stage Python 3.13 image with OCI labels, license attribution, and healthcheck. |\n| `requirements.txt` | Runtime dependencies. |\n| Langfuse tracing | Pre-configured via `agentsystems-toolkit` for observability. |\n\n**Note**: Agent metadata (model dependencies, egress requirements, setup instructions) is defined in the [agent-index](https://github.com/agentsystems/agent-index) when you publish your agent, not in the container itself.\n\n---\n\n## Where it fits\n\n```mermaid\ngraph LR\n  client((Client)) --\u003e gateway[Gateway]\n  gateway --\u003e agent((Your-Agent))\n  agent --\u003e lf[Langfuse]\n```\n\n1. Client calls `POST /your-agent` on the Gateway.\n2. Gateway forwards to your container’s `/invoke` endpoint and injects `X-Thread-Id`.\n3. Your code adds Langfuse traces and responds with JSON.\n\n---\n\n## Quick start\n\n### Run via Docker Compose (spec-compliant)\n\n```bash\ndocker compose -f compose/docker-standard.yml up --build\n```\n\nAfter a few seconds check \u003chttp://localhost:8000/docs\u003e for the swagger UI.\n\n---\n\n### Run with hot-reload (local python)\n\n1. Click **\"Use this template\"** on GitHub and create a new repository (e.g. `johndoe/my-agent`).\n2. Clone your new repo and customize `main.py`:\n   - Update the FastAPI app metadata (lines 38-42)\n   - Modify the `State`, `InvokeRequest`, and `InvokeResponse` models\n   - Implement your agent logic in the graph nodes\n3. Start the agent locally with hot-reload:\n\n```bash\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\nuvicorn main:app --reload --port 8000\n```\n\nOpen \u003chttp://localhost:8000/docs\u003e to test the `/invoke` endpoint.\n\n---\n## Container health check\n\nAgentSystems CLI waits until Docker marks your container `healthy` before routing traffic. Add a simple `HEALTHCHECK` to your `Dockerfile` so the platform knows when the agent is ready:\n\n```dockerfile\n# after EXPOSE 8000\nENV PORT 8000\nHEALTHCHECK --interval=10s --retries=3 CMD curl -sf http://localhost:${PORT}/health || exit 1\n```\n\nThe template exposes a `GET /health` endpoint that returns 200, so the example healthcheck will work with the default app.\n\n---\n## Build a Docker image\n\nBuild your agent image with standard Docker commands:\n\n```bash\ndocker build -t yourname/my-agent:0.1.0 .\n```\n\nTo embed metadata in OCI labels (recommended):\n\n```bash\ndocker build \\\n  --build-arg AGENT_NAME=\"my-agent\" \\\n  --build-arg AGENT_DESCRIPTION=\"My custom agent\" \\\n  --build-arg AGENT_DEVELOPER=\"yourname\" \\\n  --build-arg VERSION=\"0.1.0\" \\\n  -t yourname/my-agent:0.1.0 \\\n  .\n```\n\nThen push to your registry:\n\n```bash\ndocker push yourname/my-agent:0.1.0\n```\n\n---\n\n## Wire into a deployment\n\nAdd the service to [`agent-platform-deployments`](https://github.com/agentsystems/agent-platform-deployments):\n\n```yaml\n# compose/local/docker-compose.yml\n  echo-agent:\n    image: mycorp/echo-agent:0.1\n    networks:\n      - agents-int\n    labels:\n      - agent.enabled=true\n      - agent.port=8000\n```\n\nThe Gateway should now route `POST /echo-agent` to your container (once the container is healthy and registered).\n\n---\n\n## Environment variables\n\n| Var | Purpose |\n|-----|---------|\n| `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | Needed for Langfuse tracing. |\n| Any model API keys | e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` – accessed in `invoke()`. |\n\n---\n\n## File Uploads \u0026 Artifacts\n\nAgents can receive file uploads and access shared artifacts through the `/artifacts` volume mounted at runtime. The platform uses a thread-centric structure where each request gets its own directory.\n\n### File Upload Workflow\n\nUpload files using multipart requests to the gateway:\n\n```bash\n# Upload file with JSON payload\ncurl -X POST http://localhost:18080/invoke/agent-template \\\n  -H \"Authorization: Bearer your-token\" \\\n  -F \"file=@input.txt\" \\\n  -F 'json={\"sync\": true}'\n```\n\n### Artifacts Directory Structure\n\n```\n/artifacts/\n├── {thread-id-1}/\n│   ├── in/          # Input files (uploaded by client)\n│   │   └── input.txt\n│   └── out/         # Output files (created by agent)\n│       └── result.txt\n└── {thread-id-2}/\n    ├── in/\n    └── out/\n```\n\n### Reading Input Files\n\n```python\n# In your agent's invoke() function\nthread_id = request.headers.get(\"X-Thread-Id\", \"\")\nin_dir = pathlib.Path(\"/artifacts\") / thread_id / \"in\"\n\n# Check for uploaded files\nif (in_dir / \"data.txt\").exists():\n    content = (in_dir / \"data.txt\").read_text()\n```\n\n### Writing Output Files\n\n```python\n# Create output directory and write results\nout_dir = pathlib.Path(\"/artifacts\") / thread_id / \"out\"\nout_dir.mkdir(parents=True, exist_ok=True)\n(out_dir / \"result.txt\").write_text(\"Processing complete\")\n```\n\n### Accessing Artifacts Outside Agents\n\nCheck artifacts from any container with the volume mounted:\n\n```bash\n# List all threads\ndocker exec local-gateway-1 ls -la /artifacts/\n\n# Read specific output file\ndocker exec local-gateway-1 cat /artifacts/{thread-id}/out/result.txt\n\n# Use CLI helper\nagentsystems artifacts-path {thread-id} result.txt\n```\n\n---\n\n## Tips \u0026 conventions\n\n* Keep the container port consistent (8080 or 8000); the Gateway connects over the internal Docker network, so host port mapping is optional.\n* You should return JSON with the `thread_id` you received – this keeps the audit log and Langfuse trace in sync.\n* Use the [Add a New Agent guide](../docs/guides/add-agent) when integrating into the full stack.\n\n---\n\n## Publishing Your Agent\n\nTo make your agent discoverable in the AgentSystems platform:\n\n1. Build and push your Docker image to a container registry\n2. Publish metadata to the [agent-index](https://github.com/agentsystems/agent-index)\n3. Users can discover and install your agent via the platform UI\n\nSee the [AgentSystems documentation](https://docs.agentsystems.ai) for detailed publishing instructions.\n\n---\n\n## Contributing\n\nIssues and PRs are welcome – feel free to open a discussion if you need changes to the template.\n\n\n## Getting Started (local)\n\n1. Use this template to create your own repository.\n2. Customize `main.py`:\n   - Update FastAPI metadata\n   - Define your request/response models\n   - Implement your agent logic\n3. Build and run locally (see sections above).\n\n   **Request contract**\n   - Client must include `Authorization: Bearer \u003ctoken\u003e` header (any placeholder for now).\n   - Gateway injects `X-Thread-Id: \u003cuuid\u003e` header before forwarding to the agent.\n\n   **Response contract**\n   - JSON must include the same `thread_id` so audit logs can correlate request/response pairs.\n\n   Example curl (once the agent is behind the gateway):\n   ```bash\n   curl -X POST localhost:18080/my-agent \\\n        -H 'Content-Type: application/json' \\\n        -d '{\"prompt\": \"Hello\"}'\n   ```\n   Response:\n   ```json\n   {\n     \"thread_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n     \"reply\": \"Echo: Hello\",\n     \"timestamp\": \"2025-06-16T09:34:00Z\"\n   }\n   ```\n4. Build \u0026 run locally:\n\n```bash\ndocker build -t my-agent .\ndocker run -p 8000:8000 my-agent\n```\n\n5. Test:\n\n```bash\ncurl -X POST localhost:8000/invoke -H 'Content-Type: application/json' \\\n     -d '{\"prompt\": \"Hello\"}'\n```\n\n\n\n## Using in deployments\n\nIn production you usually build \u0026 push the image, then reference it in the deployment bundle stored in [`agent-platform-deployments`](https://github.com/agentsystems/agent-platform-deployments).\n\n```\n# example snippet in compose/local/docker-compose.yml\nmy-agent:\n  image: mycorp/my-agent:1.0\n  labels:\n    - agent.enabled=true\n    - agent.port=8000\n```\n\nThe Gateway will auto-discover the container and route `POST /my-agent` to its `/invoke` endpoint.\n\n---\n\n## Continuous Integration (GitHub Actions)\n\nThe project ships with a `ci.yml` workflow that now goes beyond linting:\n\n1. Runs pre-commit hooks (ruff, black, shellcheck, hadolint).\n2. Builds the agent Docker image.\n3. Starts the container mapped to `localhost:9800` (internal port 8000).\n4. Polls `http://localhost:9800/health` for up to 60 s and fails the job if the endpoint never returns **200 OK**.\n5. Removes the container in a cleanup step.\n\nThis helps verify that PRs produce images that boot successfully and expose the health endpoint.\n\n## License\n\nLicensed under the [Apache-2.0 license](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentsystems%2Fagent-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentsystems%2Fagent-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentsystems%2Fagent-template/lists"}