{"id":47061439,"url":"https://github.com/aleostudio/ai-agent","last_synced_at":"2026-03-12T04:07:32.799Z","repository":{"id":340537476,"uuid":"950011037","full_name":"aleostudio/ai-agent","owner":"aleostudio","description":"Simple AI agent with MCP/A2A client","archived":false,"fork":false,"pushed_at":"2026-03-10T17:24:55.000Z","size":96,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-10T19:35:35.225Z","etag":null,"topics":["a2a","a2a-client","a2a-protocol","agentic-ai","ai","ai-agent","ai-agents","llm","mcp","mcp-client"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aleostudio.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-17T13:46:14.000Z","updated_at":"2026-03-10T17:22:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aleostudio/ai-agent","commit_stats":null,"previous_names":["aleostudio/ai-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aleostudio/ai-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleostudio%2Fai-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleostudio%2Fai-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleostudio%2Fai-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleostudio%2Fai-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aleostudio","download_url":"https://codeload.github.com/aleostudio/ai-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleostudio%2Fai-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30415042,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["a2a","a2a-client","a2a-protocol","agentic-ai","ai","ai-agent","ai-agents","llm","mcp","mcp-client"],"created_at":"2026-03-12T04:07:31.023Z","updated_at":"2026-03-12T04:07:32.788Z","avatar_url":"https://github.com/aleostudio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI agent with MCP/A2A client\n\nThis agent will interact with an existing **Ollama** instance or other AI providers as a chatbot and it has built-in **MCP** and **A2A clients** (as orchestrator or simple client) to connect to remote MCP servers or A2A registry to use their **tools**.\n\n## Index\n\n- [Prerequisites](#prerequisites)\n- [Configuration](#configuration)\n- [Scaffold new agent](#scaffold-new-agent)\n- [Run service](#run-service)\n- [Customize system prompt](#customize-system-prompt)\n- [UI for debug](#ui-for-debug)\n- [Tests](#tests)\n- [Debug in VSCode](#debug-in-vscode)\n- [License](#license)\n\n---\n\n## Prerequisites\n\n- Python \u003e= 3.13 (recommended: 3.13)\n- [uv](https://docs.astral.sh/uv/getting-started/installation) and [pip](https://pip.pypa.io/en/stable/installation) installed\n\n[↑ index](#index)\n\n---\n\n## Configuration\n\nInit **virtualenv** and install dependencies with:\n\n```bash\nuv venv --python 3.13\nsource .venv/bin/activate\nuv sync\n```\n\nCreate your ```.env``` file by copying:\n\n```bash\ncp env.dist .env\n```\n\nThen, customize it if needed (e.g. **model**, **temperature** and so on).\n\nIf you want to **enable MCP support**, update these env vars with your URL (`MCP_SERVERS` is in JSON array format; you can add several servers):\n\n```bash\nMCP_ENABLED=True\nMCP_SERVERS='[{\"name\": \"mcp-server\", \"transport\": \"sse\", \"url\": \"http://localhost:8000/sse\"}]'\n```\n\nIf you want to **enable A2A support**, set these variables:\n\n```bash\nA2A_ENABLED=true\nA2A_ROLE=orchestrator\nREGISTRY_URL=http://localhost:9300\n```\n\nPay attention that `orchestrator` will use **other A2A agents** discovered by A2A registry. If you set `client` as role, this agent will work as a specific A2A agent, called by another A2A orchestrator.\n\n\u003e **NOTE**:\n\u003e to work properly, tool calling needs a fairly intelligent model, so consider using at least a **8b model** or more.\n\nIf you want to **stream** the agent response, change this variable in:\n\n```bash\nRESPONSE_TYPE=\"stream\"\n```\n\nIf you want to run in **pure A2A mode** (without FastAPI HTTP APIs like `/interact`, `/tools`, `/ui`, `/`), set:\n\n```bash\nA2A_ENABLED=true\nHTTP_API_ENABLED=false\n```\n\n\u003e `HTTP_API_ENABLED=false` requires `A2A_ENABLED=true`.\n\n[↑ index](#index)\n\n---\n\n## Scaffold new agent\n\nTo clone this boilerplate into a new agent folder with renamed classes/files and updated port/card metadata:\n\n```bash\npython scripts/create_agent.py\n```\n\nor with Makefile:\n\n```bash\nmake scaffold\n```\n\nBefore running it, edit the variables at the top of:\n\n```bash\nscripts/create_agent.py\n```\n\n[↑ index](#index)\n\n---\n\n## Run service\n\nIf you want to run the service through your local **uvicorn** to customize host or port:\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 9201\n```\n\nIf you prefer, there is a **shortcut script** with predefined port:\n\n```bash\nsh run.sh\n```\n\nor simply with the built-in **Makefile**\n\n```bash\nmake\n```\n\nIf you want to use **Docker**, build and run with:\n\n```bash\ndocker-compose build\ndocker-compose up -d\n```\n\nCheck if app is up \u0026 running\n\n```bash\ncurl -XGET \"http://localhost:9201\"\n```\n\nYou can start the conversation with this simple payload:\n\n```bash\ncurl -XPOST \"http://localhost:9201/interact\" \\\n--header \"Content-Type: application/json\" \\\n--data '{\n    \"prompt\": \"Hi! Who are you?\"\n}'\n```\n\nThe response will be something like this payload:\n\n```json\n{\n    \"response\": {\n        \"content\": \"Hello! I'm a helpful assistant here to assist with any questions or tasks you may have. I'm designed to provide clear and accurate information on a wide range of topics, from science and history to entertainment and culture. Feel free to ask me anything, and I'll do my best to help!\",\n        \"additional_kwargs\": {},\n        \"response_metadata\": {\n            \"model\": \"llama3.2\",\n            \"created_at\": \"2025-03-17T16:34:39.038796Z\",\n            \"done\": true,\n            \"done_reason\": \"stop\",\n            \"total_duration\": 6812295667,\n            \"load_duration\": 41449333,\n            \"prompt_eval_count\": 40,\n            \"prompt_eval_duration\": 138000000,\n            \"eval_count\": 335,\n            \"eval_duration\": 6631000000,\n            \"message\": {\n                \"role\": \"assistant\",\n                \"content\": \"\",\n                \"images\": null,\n                \"tool_calls\": null\n            }\n        },\n        \"type\": \"ai\",\n        \"name\": null,\n        \"id\": \"run-d8728972-8cad-408c-8316-511dd36a5b79-0\",\n        \"example\": false,\n        \"tool_calls\": [],\n        \"invalid_tool_calls\": [],\n        \"usage_metadata\": {\n            \"input_tokens\": 40,\n            \"output_tokens\": 335,\n            \"total_tokens\": 375\n        }\n    }\n}\n```\n\n[↑ index](#index)\n\n\u003e If `HTTP_API_ENABLED=false`, these HTTP endpoints are disabled and only the A2A server is exposed.\n\n---\n\n## Customize system prompt\n\nIn order to customize **system prompts** open the file `app/prompts.py`.\nHere you will find:\n\n### SYSTEM_PROMPT\n\nThis prompt is used for **standard LLM agent** (generic questions like chatbot).\n\nSet `MCP_ENABLED` and `A2A_ENABLED` to `false` and call the agent via API.\n\n### SYSTEM_PROMPT_A2A_ORCH\n\nThis prompt is used for **A2A orchestrator agent** (an orchestrator that route\nthe request to other A2A agents). The agents are dynamically injected inside the\nprompt, reading the agents list from A2A registry.\n\nSet `A2A_ENABLED` to `true` and `A2A_ROLE` to `orchestrator`.\n\n### SYSTEM_PROMPT_A2A_CLIENT\n\nIf you need to expose a specific tool through A2A, you need to customize this prompt.\nAn orchestrator will read your card (`app/a2a_card.py`) and will route the request to this agent.\n\nSet `A2A_ENABLED` to `true` and `A2A_ROLE` to `client`.\n\n### TOOLS_SECTION\n\nAppended dynamically to any base prompt when tools are available (MCP or A2A routing).\nEnforces rules to prevent the model from leaking tool names or JSON in responses.\n\n[↑ index](#index)\n\n---\n\n### UI for debug\n\nIf you want to test the agent through an UI, there is a built-in ChatGPT-like UI at [this address](http://localhost:9201/ui).\n\n[↑ index](#index)\n\n---\n\n## Tests\n\nEnsure you have ```pytest``` installed, otherwise:\n\n```bash\nuv pip install pytest\n```\n\nThen, launch tests with:\n\n```bash\npytest tests/\n```\n\n[↑ index](#index)\n\n---\n\n## Debug in VSCode\n\nTo debug your Python microservice you need to:\n\n- Install **VSCode**\n- Ensure you have **Python extension** installed\n- Ensure you have selected the **right interpreter with virtualenv** on VSCode\n- Click on **Run and Debug** menu and **create a launch.json file**\n- From dropdown, select **Python debugger** and **FastAPI**\n- Change the ```.vscode/launch.json``` created in the project root with this (customizing host and port if changed):\n\n```json\n{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"FastAPI Debug\",\n            \"type\": \"debugpy\",\n            \"request\": \"launch\",\n            \"module\": \"uvicorn\",\n            \"args\": [\n                \"app.main:app\",\n                \"--host\", \"0.0.0.0\",\n                \"--port\", \"9201\",\n                \"--reload\"\n            ],\n            \"envFile\": \"${workspaceFolder}/.env\",\n            \"console\": \"integratedTerminal\",\n            \"cwd\": \"${workspaceFolder}\",\n            \"justMyCode\": true\n        }\n    ]\n}\n```\n\n- Put some breakpoint in the code, then press the **green play button**\n- Call the API to debug\n\n[↑ index](#index)\n\n---\n\n## License\n\nThis project is licensed under the MIT License.\n\n[↑ index](#index)\n\n---\n\nMade with ♥️ by Alessandro Orrù\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faleostudio%2Fai-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faleostudio%2Fai-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faleostudio%2Fai-agent/lists"}