<div align="center">
<img alt="utcp agent logo" src="https://github.com/user-attachments/assets/77723130-ecbc-4d1d-9e9b-20f978882699" width="80%" style="margin: 20px auto;">
<h1 align="center">🚀 Ready-to-use agent with intelligent tool-calling capabilities</h1>
<p align="center">
<a href="https://github.com/universal-tool-calling-protocol">
<img src="https://img.shields.io/github/followers/universal-tool-calling-protocol?label=Follow%20Org&logo=github" /></a>
<a href="https://pypi.org/project/utcp-agent/" title="PyPI Version">
<img src="https://img.shields.io/pypi/v/utcp-agent.svg"/></a>
<a href="https://github.com/universal-tool-calling-protocol/utcp-agent/blob/main/LICENSE" alt="License">
<img src="https://img.shields.io/github/license/universal-tool-calling-protocol/utcp-agent" /></a>
<a href="https://utcp.io/" alt="Documentation">
<img src="https://img.shields.io/badge/docs-utcp.io-blue" /></a>
</p>
</div>
**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.
The 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.
## Features
| Feature | Description |
| :--- | :--- |
| **🤖 Intelligent Tool Discovery** | Automatically searches and selects relevant UTCP tools based on user queries. |
| **🌐 Multi-LLM Support**| Compatible with OpenAI, Anthropic, and other LangChain-supported language models. |
| **🔄 LangGraph Workflow** | Uses LangGraph for structured agent execution with proper state management. |
| **💨 Streaming Support** | Optional streaming of workflow execution steps for real-time feedback. |
| **🧠 Conversation Memory** | Built-in conversation history and checkpointing for continuous conversations. |
| **🔧 Flexible Configuration** | Easily configurable through UTCP client config and agent config. |
## Quick Start
### Installation
```bash
pip install utcp-agent langchain-openai
```
Set your API key:
```bash
export OPENAI_API_KEY=your_api_key_here
```
### Spin up your agent:
```python
import asyncio
import os
from langchain_openai import ChatOpenAI
from utcp_agent import UtcpAgent
async def main():
# Set your OpenAI API key
llm = ChatOpenAI(
model="gpt-4o-mini",
api_key=os.getenv("OPENAI_API_KEY")
)
# Create agent with book search capability
agent = await UtcpAgent.create(
llm=llm,
utcp_config={
"manual_call_templates": [{
"name": "openlibrary",
"call_template_type": "http",
"http_method": "GET",
"url": "https://openlibrary.org/static/openapi.json",
"content_type": "application/json"
}]
}
)
# Chat with the agent
response = await agent.chat("Can you search for books by George Orwell?")
print(f"Agent: {response}")
if __name__ == "__main__":
asyncio.run(main())
```
## Advanced Configuration
### With Memory and Custom Prompts
```python
from utcp_agent import UtcpAgent, UtcpAgentConfig
from langgraph.checkpoint.memory import MemorySaver
agent_config = UtcpAgentConfig(
max_tools_per_search=10,
checkpointer=MemorySaver(),
system_prompt="You are a helpful AI assistant with access to various tools through UTCP."
)
agent = await UtcpAgent.create(
llm=llm,
utcp_config=utcp_config,
agent_config=agent_config
)
# Use thread_id for conversation continuity
response = await agent.chat("Find me a science fiction book", thread_id="user_1")
```
### With Environment Variables
```python
from pathlib import Path
utcp_config = {
"load_variables_from": [{
"variable_loader_type": "dotenv",
"env_file_path": str(Path(__file__).parent / ".env")
}],
"manual_call_templates": [{
"name": "openlibrary",
"call_template_type": "http",
"http_method": "GET",
"url": "https://openlibrary.org/static/openapi.json",
"content_type": "application/json"
}]
}
```
### Streaming Execution
```python
async for step in agent.stream("Search for AI books"):
print(f"Step: {step}")
```
## Workflow
The agent follows a structured workflow using LangGraph, a library for building stateful, multi-actor applications with LLMs.
1. **Analyze Task**: Understands the user's query and formulates the current task.
2. **Search Tools**: Uses UTCP to find relevant tools for the task.
3. **Decide Action**: Determines whether to call tools or respond directly.
4. **Execute Tools**: Calls the selected tool with appropriate arguments.
5. **Respond**: Formats and returns the final response to the user.
```mermaid
graph TD
A[User Input] --> B[Analyze Task]
B --> C[Search Tools]
C --> D[Decide Action]
D --> E{Action Type}
E -->|Call Tool| F[Execute Tools]
E -->|Respond| G[Generate Response]
F --> G
G --> H[End]
```
## Examples
See the [`examples/` directory](https://github.com/universal-tool-calling-protocol/utcp-agent/tree/main/examples) for comprehensive examples:
* **`basic_openai.py`**: Using GPT models with book search.
* **`basic_anthropic.py`**: Using Claude models.
* **`streaming_example.py`**: Real-time workflow monitoring.
* **`config_file_example.py`**: Loading UTCP configuration from files.
* **`memory_conversation.py`**: Multi-turn conversations with memory.
## Configuration Options
### UtcpAgentConfig
| Option | Description |
| :--- | :--- |
| `max_iterations` | Maximum workflow iterations (default: 3). |
| `max_tools_per_search` | Maximum tools to retrieve per search (default: 10). |
| `system_prompt` | Custom system prompt for the agent. |
| `checkpointer`| LangGraph checkpointer for conversation memory. |
| `callbacks` | LangChain callbacks for observability. |
| `summarize_threshold` | Token count threshold for context summarization (default: 80000). |
### UTCP Configuration
The agent accepts a standard UTCP client configuration, which can include:
* Variable definitions and loading
* Manual call templates
* Tool provider configurations
## API Reference
### UtcpAgent
#### Class Methods
* `create(llm, utcp_config=None, agent_config=None, root_dir=None)`
* Creates and initializes a UtcpAgent with an automatic UTCP client.
#### Instance Methods
* `chat(user_input: str, thread_id: Optional[str] = None) -> str`
* Processes user input and returns the agent's response.
* Use `thread_id` for maintaining conversational continuity.
* `stream(user_input: str, thread_id: Optional[str] = None)`
* Streams the workflow execution steps.
## Error Handling
The agent includes comprehensive error handling to manage:
* Tool execution failures
* JSON parsing errors in LLM responses
* UTCP client errors
* Fallback responses to ensure the agent always provides a reply
## Logging
Enable logging to monitor the agent's behavior:
```python
import logging
logging.basicConfig(level=logging.INFO)
# Disable UTCP library logging for cleaner output
logging.getLogger("utcp").setLevel(logging.WARNING)
```
## Contributing
1. Follow the existing code style and patterns
2. Add tests for new functionality
3. Update documentation for API changes
4. Ensure compatibility with UTCP core library
## License
See LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "utcp-agent",
"maintainer": "UTCP Team",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, agent, utcp, langgraph, langchain, tools",
"author": "UTCP Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/23/8f/f8bfbf4a48045afaac106620b6459ffb0500dd65cc02462f058365239302/utcp_agent-1.0.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\r\n<img alt=\"utcp agent logo\" src=\"https://github.com/user-attachments/assets/77723130-ecbc-4d1d-9e9b-20f978882699\" width=\"80%\" style=\"margin: 20px auto;\">\r\n\r\n<h1 align=\"center\">\ud83d\ude80 Ready-to-use agent with intelligent tool-calling capabilities</h1>\r\n<p align=\"center\">\r\n <a href=\"https://github.com/universal-tool-calling-protocol\">\r\n <img src=\"https://img.shields.io/github/followers/universal-tool-calling-protocol?label=Follow%20Org&logo=github\" /></a>\r\n <a href=\"https://pypi.org/project/utcp-agent/\" title=\"PyPI Version\">\r\n <img src=\"https://img.shields.io/pypi/v/utcp-agent.svg\"/></a>\r\n <a href=\"https://github.com/universal-tool-calling-protocol/utcp-agent/blob/main/LICENSE\" alt=\"License\">\r\n <img src=\"https://img.shields.io/github/license/universal-tool-calling-protocol/utcp-agent\" /></a>\r\n <a href=\"https://utcp.io/\" alt=\"Documentation\">\r\n <img src=\"https://img.shields.io/badge/docs-utcp.io-blue\" /></a>\r\n</p>\r\n</div>\r\n\r\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.\r\n\r\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.\r\n\r\n## Features\r\n\r\n| Feature | Description |\r\n| :--- | :--- |\r\n| **\ud83e\udd16 Intelligent Tool Discovery** | Automatically searches and selects relevant UTCP tools based on user queries. |\r\n| **\ud83c\udf10 Multi-LLM Support**| Compatible with OpenAI, Anthropic, and other LangChain-supported language models. |\r\n| **\ud83d\udd04 LangGraph Workflow** | Uses LangGraph for structured agent execution with proper state management. |\r\n| **\ud83d\udca8 Streaming Support** | Optional streaming of workflow execution steps for real-time feedback. |\r\n| **\ud83e\udde0 Conversation Memory** | Built-in conversation history and checkpointing for continuous conversations. |\r\n| **\ud83d\udd27 Flexible Configuration** | Easily configurable through UTCP client config and agent config. |\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install utcp-agent langchain-openai\r\n```\r\n\r\nSet your API key:\r\n```bash\r\nexport OPENAI_API_KEY=your_api_key_here\r\n```\r\n\r\n### Spin up your agent:\r\n\r\n```python\r\nimport asyncio\r\nimport os\r\nfrom langchain_openai import ChatOpenAI\r\nfrom utcp_agent import UtcpAgent\r\n\r\nasync def main():\r\n # Set your OpenAI API key\r\n llm = ChatOpenAI(\r\n model=\"gpt-4o-mini\",\r\n api_key=os.getenv(\"OPENAI_API_KEY\")\r\n )\r\n \r\n # Create agent with book search capability\r\n agent = await UtcpAgent.create(\r\n llm=llm,\r\n utcp_config={\r\n \"manual_call_templates\": [{\r\n \"name\": \"openlibrary\",\r\n \"call_template_type\": \"http\",\r\n \"http_method\": \"GET\",\r\n \"url\": \"https://openlibrary.org/static/openapi.json\",\r\n \"content_type\": \"application/json\"\r\n }]\r\n }\r\n )\r\n \r\n # Chat with the agent\r\n response = await agent.chat(\"Can you search for books by George Orwell?\")\r\n print(f\"Agent: {response}\")\r\n\r\nif __name__ == \"__main__\":\r\n asyncio.run(main())\r\n```\r\n\r\n## Advanced Configuration\r\n\r\n### With Memory and Custom Prompts\r\n\r\n```python\r\nfrom utcp_agent import UtcpAgent, UtcpAgentConfig\r\nfrom langgraph.checkpoint.memory import MemorySaver\r\n\r\nagent_config = UtcpAgentConfig(\r\n max_tools_per_search=10,\r\n checkpointer=MemorySaver(),\r\n system_prompt=\"You are a helpful AI assistant with access to various tools through UTCP.\"\r\n)\r\n\r\nagent = await UtcpAgent.create(\r\n llm=llm,\r\n utcp_config=utcp_config,\r\n agent_config=agent_config\r\n)\r\n\r\n# Use thread_id for conversation continuity\r\nresponse = await agent.chat(\"Find me a science fiction book\", thread_id=\"user_1\")\r\n```\r\n\r\n### With Environment Variables\r\n\r\n```python\r\nfrom pathlib import Path\r\n\r\nutcp_config = {\r\n \"load_variables_from\": [{\r\n \"variable_loader_type\": \"dotenv\",\r\n \"env_file_path\": str(Path(__file__).parent / \".env\")\r\n }],\r\n \"manual_call_templates\": [{\r\n \"name\": \"openlibrary\",\r\n \"call_template_type\": \"http\", \r\n \"http_method\": \"GET\",\r\n \"url\": \"https://openlibrary.org/static/openapi.json\",\r\n \"content_type\": \"application/json\"\r\n }]\r\n}\r\n```\r\n\r\n### Streaming Execution\r\n\r\n```python\r\nasync for step in agent.stream(\"Search for AI books\"):\r\n print(f\"Step: {step}\")\r\n```\r\n\r\n## Workflow\r\n\r\nThe agent follows a structured workflow using LangGraph, a library for building stateful, multi-actor applications with LLMs.\r\n\r\n1. **Analyze Task**: Understands the user's query and formulates the current task.\r\n2. **Search Tools**: Uses UTCP to find relevant tools for the task.\r\n3. **Decide Action**: Determines whether to call tools or respond directly.\r\n4. **Execute Tools**: Calls the selected tool with appropriate arguments.\r\n5. **Respond**: Formats and returns the final response to the user.\r\n\r\n```mermaid\r\ngraph TD\r\n A[User Input] --> B[Analyze Task]\r\n B --> C[Search Tools]\r\n C --> D[Decide Action]\r\n D --> E{Action Type}\r\n E -->|Call Tool| F[Execute Tools]\r\n E -->|Respond| G[Generate Response]\r\n F --> G\r\n G --> H[End]\r\n```\r\n\r\n## Examples\r\n\r\nSee the [`examples/` directory](https://github.com/universal-tool-calling-protocol/utcp-agent/tree/main/examples) for comprehensive examples:\r\n\r\n* **`basic_openai.py`**: Using GPT models with book search.\r\n* **`basic_anthropic.py`**: Using Claude models.\r\n* **`streaming_example.py`**: Real-time workflow monitoring.\r\n* **`config_file_example.py`**: Loading UTCP configuration from files.\r\n* **`memory_conversation.py`**: Multi-turn conversations with memory.\r\n\r\n## Configuration Options\r\n\r\n### UtcpAgentConfig\r\n\r\n| Option | Description |\r\n| :--- | :--- |\r\n| `max_iterations` | Maximum workflow iterations (default: 3). |\r\n| `max_tools_per_search` | Maximum tools to retrieve per search (default: 10). |\r\n| `system_prompt` | Custom system prompt for the agent. |\r\n| `checkpointer`| LangGraph checkpointer for conversation memory. |\r\n| `callbacks` | LangChain callbacks for observability. |\r\n| `summarize_threshold` | Token count threshold for context summarization (default: 80000). |\r\n\r\n### UTCP Configuration\r\n\r\nThe agent accepts a standard UTCP client configuration, which can include:\r\n* Variable definitions and loading\r\n* Manual call templates\r\n* Tool provider configurations\r\n\r\n## API Reference\r\n\r\n### UtcpAgent\r\n\r\n#### Class Methods\r\n\r\n* `create(llm, utcp_config=None, agent_config=None, root_dir=None)`\r\n * Creates and initializes a UtcpAgent with an automatic UTCP client.\r\n\r\n#### Instance Methods\r\n\r\n* `chat(user_input: str, thread_id: Optional[str] = None) -> str`\r\n * Processes user input and returns the agent's response.\r\n * Use `thread_id` for maintaining conversational continuity.\r\n\r\n* `stream(user_input: str, thread_id: Optional[str] = None)`\r\n * Streams the workflow execution steps.\r\n\r\n## Error Handling\r\n\r\nThe agent includes comprehensive error handling to manage:\r\n* Tool execution failures\r\n* JSON parsing errors in LLM responses\r\n* UTCP client errors\r\n* Fallback responses to ensure the agent always provides a reply\r\n\r\n## Logging\r\n\r\nEnable logging to monitor the agent's behavior:\r\n\r\n```python\r\nimport logging\r\nlogging.basicConfig(level=logging.INFO)\r\n# Disable UTCP library logging for cleaner output\r\nlogging.getLogger(\"utcp\").setLevel(logging.WARNING)\r\n\r\n```\r\n\r\n## Contributing\r\n\r\n1. Follow the existing code style and patterns\r\n2. Add tests for new functionality\r\n3. Update documentation for API changes\r\n4. Ensure compatibility with UTCP core library\r\n\r\n## License\r\n\r\nSee LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A ready-to-use agent for UTCP tool calling",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://utcp.io",
"Issues": "https://github.com/universal-tool-calling-protocol/utcp-agent/issues",
"Source": "https://github.com/universal-tool-calling-protocol/utcp-agent"
},
"split_keywords": [
"ai",
" agent",
" utcp",
" langgraph",
" langchain",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1b44c1f68538f10ca383fa04b2d4d6e5e29b0e091ce32412f193ca0fb83be0b0",
"md5": "bb030baf2fb2ab02e105bb9a522e426c",
"sha256": "c909a4c313297d508dbecbf3a899938e8f84e4efefcf37aefef66873669fbacb"
},
"downloads": -1,
"filename": "utcp_agent-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb030baf2fb2ab02e105bb9a522e426c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16868,
"upload_time": "2025-09-05T14:26:11",
"upload_time_iso_8601": "2025-09-05T14:26:11.335331Z",
"url": "https://files.pythonhosted.org/packages/1b/44/c1f68538f10ca383fa04b2d4d6e5e29b0e091ce32412f193ca0fb83be0b0/utcp_agent-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "238ff8bfbf4a48045afaac106620b6459ffb0500dd65cc02462f058365239302",
"md5": "255c50d637fa97f2263260b1a7bd29ab",
"sha256": "783d02850b1d8f024e64e49f7e3030c44f85802f75e79fc770183389661e9411"
},
"downloads": -1,
"filename": "utcp_agent-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "255c50d637fa97f2263260b1a7bd29ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19787,
"upload_time": "2025-09-05T14:26:12",
"upload_time_iso_8601": "2025-09-05T14:26:12.335631Z",
"url": "https://files.pythonhosted.org/packages/23/8f/f8bfbf4a48045afaac106620b6459ffb0500dd65cc02462f058365239302/utcp_agent-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 14:26:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "universal-tool-calling-protocol",
"github_project": "utcp-agent",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "utcp-agent"
}
JSON
