{"id":30948269,"url":"https://github.com/universal-tool-calling-protocol/utcp-agent","last_synced_at":"2026-01-24T16:22:43.774Z","repository":{"id":312063431,"uuid":"1045025179","full_name":"universal-tool-calling-protocol/utcp-agent","owner":"universal-tool-calling-protocol","description":"Ready-to-use agent that can interact directly with any tool or native endpoint, in less than 5 lines of code","archived":false,"fork":false,"pushed_at":"2025-09-05T14:27:05.000Z","size":52,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T08:57:41.566Z","etag":null,"topics":["agent","agents","ai","artificial-intelligence","python","tools","utcp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/universal-tool-calling-protocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-08-26T14:45:22.000Z","updated_at":"2025-09-05T17:02:47.000Z","dependencies_parsed_at":"2025-08-28T16:23:59.576Z","dependency_job_id":null,"html_url":"https://github.com/universal-tool-calling-protocol/utcp-agent","commit_stats":null,"previous_names":["universal-tool-calling-protocol/utcp-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/universal-tool-calling-protocol/utcp-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Futcp-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Futcp-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Futcp-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Futcp-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/universal-tool-calling-protocol","download_url":"https://codeload.github.com/universal-tool-calling-protocol/utcp-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Futcp-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274563687,"owners_count":25308463,"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","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"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":["agent","agents","ai","artificial-intelligence","python","tools","utcp"],"created_at":"2025-09-11T02:02:23.473Z","updated_at":"2026-01-24T16:22:43.766Z","avatar_url":"https://github.com/universal-tool-calling-protocol.png","language":"Python","funding_links":[],"categories":["HarmonyOS","Communication Protocols"],"sub_categories":["Windows Manager"],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg alt=\"utcp agent logo\" src=\"https://github.com/user-attachments/assets/77723130-ecbc-4d1d-9e9b-20f978882699\" width=\"80%\" style=\"margin: 20px auto;\"\u003e\n\n\u003ch1 align=\"center\"\u003e🚀 Ready-to-use agent with intelligent tool-calling capabilities\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/universal-tool-calling-protocol\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/followers/universal-tool-calling-protocol?label=Follow%20Org\u0026logo=github\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/utcp-agent/\" title=\"PyPI Version\"\u003e\n        \u003cimg src=\"https://img.shields.io/pypi/v/utcp-agent.svg\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/universal-tool-calling-protocol/utcp-agent/blob/main/LICENSE\" alt=\"License\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/license/universal-tool-calling-protocol/utcp-agent\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://utcp.io/\" alt=\"Documentation\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/docs-utcp.io-blue\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n**UTCP Agent** is the easiest way to build custom, ready-to-use agents which have intelligent tool calling capabilities and can connect to any native endpoint. The agent automatically discovers, searches, and executes UTCP tools based on user queries.\n\nThe Universal Tool Calling Protocol (UTCP) is an open standard that enables AI agents to discover and directly call tools across various communication protocols, eliminating the need for wrapper servers and reducing latency.\n\n## Features\n\n| Feature | Description |\n| :--- | :--- |\n| **🤖 Intelligent Tool Discovery** | Automatically searches and selects relevant UTCP tools based on user queries. |\n| **🌐 Multi-LLM Support**| Compatible with OpenAI, Anthropic, and other LangChain-supported language models. |\n| **🔄 LangGraph Workflow** | Uses LangGraph for structured agent execution with proper state management. |\n| **💨 Streaming Support** | Optional streaming of workflow execution steps for real-time feedback. |\n| **🧠 Conversation Memory** | Built-in conversation history and checkpointing for continuous conversations. |\n| **🔧 Flexible Configuration** | Easily configurable through UTCP client config and agent config. |\n\n## Quick Start\n\n### Installation\n\n```bash\npip install utcp-agent langchain-openai\n```\n\nSet your API key:\n```bash\nexport OPENAI_API_KEY=your_api_key_here\n```\n\n### Spin up your agent:\n\n```python\nimport asyncio\nimport os\nfrom langchain_openai import ChatOpenAI\nfrom utcp_agent import UtcpAgent\n\nasync def main():\n    # Set your OpenAI API key\n    llm = ChatOpenAI(\n        model=\"gpt-4o-mini\",\n        api_key=os.getenv(\"OPENAI_API_KEY\")\n    )\n    \n    # Create agent with book search capability\n    agent = await UtcpAgent.create(\n        llm=llm,\n        utcp_config={\n            \"manual_call_templates\": [{\n                \"name\": \"openlibrary\",\n                \"call_template_type\": \"http\",\n                \"http_method\": \"GET\",\n                \"url\": \"https://openlibrary.org/static/openapi.json\",\n                \"content_type\": \"application/json\"\n            }]\n        }\n    )\n    \n    # Chat with the agent\n    response = await agent.chat(\"Can you search for books by George Orwell?\")\n    print(f\"Agent: {response}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## Advanced Configuration\n\n### With Memory and Custom Prompts\n\n```python\nfrom utcp_agent import UtcpAgent, UtcpAgentConfig\nfrom langgraph.checkpoint.memory import MemorySaver\n\nagent_config = UtcpAgentConfig(\n    max_tools_per_search=10,\n    checkpointer=MemorySaver(),\n    system_prompt=\"You are a helpful AI assistant with access to various tools through UTCP.\"\n)\n\nagent = await UtcpAgent.create(\n    llm=llm,\n    utcp_config=utcp_config,\n    agent_config=agent_config\n)\n\n# Use thread_id for conversation continuity\nresponse = await agent.chat(\"Find me a science fiction book\", thread_id=\"user_1\")\n```\n\n### With Environment Variables\n\n```python\nfrom pathlib import Path\n\nutcp_config = {\n    \"load_variables_from\": [{\n        \"variable_loader_type\": \"dotenv\",\n        \"env_file_path\": str(Path(__file__).parent / \".env\")\n    }],\n    \"manual_call_templates\": [{\n        \"name\": \"openlibrary\",\n        \"call_template_type\": \"http\", \n        \"http_method\": \"GET\",\n        \"url\": \"https://openlibrary.org/static/openapi.json\",\n        \"content_type\": \"application/json\"\n    }]\n}\n```\n\n### Streaming Execution\n\n```python\nasync for step in agent.stream(\"Search for AI books\"):\n    print(f\"Step: {step}\")\n```\n\n## Workflow\n\nThe agent follows a structured workflow using LangGraph, a library for building stateful, multi-actor applications with LLMs.\n\n1.  **Analyze Task**: Understands the user's query and formulates the current task.\n2.  **Search Tools**: Uses UTCP to find relevant tools for the task.\n3.  **Decide Action**: Determines whether to call tools or respond directly.\n4.  **Execute Tools**: Calls the selected tool with appropriate arguments.\n5.  **Respond**: Formats and returns the final response to the user.\n\n```mermaid\ngraph TD\n    A[User Input] --\u003e B[Analyze Task]\n    B --\u003e C[Search Tools]\n    C --\u003e D{Decide Action}\n    D --\u003e|Call Tool| F[Execute Tools]\n    D --\u003e|Respond| G[Generate Response]\n    F --\u003e B\n    G --\u003e H[End]\n```\n\n## Examples\n\nSee the [`examples/` directory](https://github.com/universal-tool-calling-protocol/utcp-agent/tree/main/examples) for comprehensive examples:\n\n*   **`basic_openai.py`**: Using GPT models with book search.\n*   **`basic_anthropic.py`**: Using Claude models.\n*   **`streaming_example.py`**: Real-time workflow monitoring.\n*   **`config_file_example.py`**: Loading UTCP configuration from files.\n*   **`memory_conversation.py`**: Multi-turn conversations with memory.\n\n## Configuration Options\n\n### UtcpAgentConfig\n\n| Option | Description |\n| :--- | :--- |\n| `max_iterations` | Maximum workflow iterations (default: 3). |\n| `max_tools_per_search` | Maximum tools to retrieve per search (default: 10). |\n| `system_prompt` | Custom system prompt for the agent. |\n| `checkpointer`| LangGraph checkpointer for conversation memory. |\n| `callbacks` | LangChain callbacks for observability. |\n| `summarize_threshold` | Token count threshold for context summarization (default: 80000). |\n\n### UTCP Configuration\n\nThe agent accepts a standard UTCP client configuration, which can include:\n*   Variable definitions and loading\n*   Manual call templates\n*   Tool provider configurations\n\n## API Reference\n\n### UtcpAgent\n\n#### Class Methods\n\n*   `create(llm, utcp_config=None, agent_config=None, root_dir=None)`\n    *   Creates and initializes a UtcpAgent with an automatic UTCP client.\n\n#### Instance Methods\n\n*   `chat(user_input: str, thread_id: Optional[str] = None) -\u003e str`\n    *   Processes user input and returns the agent's response.\n    *   Use `thread_id` for maintaining conversational continuity.\n\n*   `stream(user_input: str, thread_id: Optional[str] = None)`\n    *   Streams the workflow execution steps.\n\n## Error Handling\n\nThe agent includes comprehensive error handling to manage:\n*   Tool execution failures\n*   JSON parsing errors in LLM responses\n*   UTCP client errors\n*   Fallback responses to ensure the agent always provides a reply\n\n## Logging\n\nEnable logging to monitor the agent's behavior:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.INFO)\n# Disable UTCP library logging for cleaner output\nlogging.getLogger(\"utcp\").setLevel(logging.WARNING)\n\n```\n\n## Contributing\n\n1. Follow the existing code style and patterns\n2. Add tests for new functionality\n3. Update documentation for API changes\n4. Ensure compatibility with UTCP core library\n\n## License\n\nSee LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funiversal-tool-calling-protocol%2Futcp-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funiversal-tool-calling-protocol%2Futcp-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funiversal-tool-calling-protocol%2Futcp-agent/lists"}