Metadata-Version: 2.4
Name: agentic-a2a
Version: 0.1.13
Summary: Python framework for implementing multi-agent systems
Home-page: https://github.com/DevTurtleBlog/agentic
Author: devturtleblog@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: uvicorn
Requires-Dist: fastapi
Requires-Dist: a2a-sdk
Requires-Dist: fastapi-mcp
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-runner; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Agentic A2A

> ⚠️ **Beta Version**: This framework is currently in active development and is considered a beta release. Features may change, and some functionality may be unstable.

A Python framework for developing and deploying complete AI applications based on the following protocols:
- Agent2Agent (A2A)
- Model Context Protocol (MCP)


## Table of contents

- [Overview](#overview)
- [Key Features](#key-features)
- [Development Status](#development-status)
- [Getting Started](#getting-started)
  - [Project structure](#project-structure)
  - [Deploy the Server](#deploy-the-server)
- [A2A](#a2a)
  - [Define an Agent](#define-an-agent)
  - [Use the A2A Client](#use-the-a2a-client)
- [MCP](#mcp)
  - [Define an MCP Tool](#define-an-mcp-tool)
  - [Integration with external MCP client](#integration-with-external-mcp-client)
- [Contributing](#contributing)
- [Links](#links)


## Overview

Agentic is a powerful framework that simplifies the creation of multi-agent systems by leveraging the a2a protocol. Built on top of [FastAPI](https://fastapi.tiangolo.com/) and the [a2a-sdk](https://github.com/google-a2a/a2a-python), Agentic enables developers to easily define, deploy, and manage multiple AI agents.
Agentic also allows the creation of tools according to the MCP standard. The MCP system is built on top of [FastApiMCP](https://github.com/tadata-org/fastapi_mcp).

Generally speaking, an Agentic application is a FastAPI application in all respects. It is therefore possible to exploit all the potential of the original framework with the addition of some utilities that simplify the implementation. For example, agentic provides a decorators system that simplifies the configuration of resources.

## Key Features

- **Simple Agent Definition**: Use `@agent` and `@skill` decorators to define agents and their capabilities with minimal boilerplate code
- **Multi-Agent Server**: Deploy multiple agents on the same server instance
- **A2A Protocol Support**: Built-in support for agent-to-agent communication using the standardized a2a protocol
- **FastAPI Integration**: Leverages FastAPI's performance and features for robust web service deployment
- **A2A Client**: Included client for easy interaction with deployed agents
- **MCP Tools**: Use `@mcp` decorator to expose tools according to the MCP standard

## Development Status

This project is currently in **beta development**. We are actively working on:
- Stabilizing the core API
- Adding comprehensive documentation
- Implementing additional features

Feedback and contributions are highly appreciated as we work towards a stable release.

## Getting Started

### Project structure:

\- app <br>
-- agents <br>
--- __init__.py <br>
--- hello_agent.py <br>
-- tools <br>
--- __init__.py <br>
--- hello_tool.py <br>
main.py <br>

### Deploy the Server:

Create the main.py file with the following content:

```python
from agentic.server import AgenticApp
AgenticApp(title="Agentic", root_package='app', port=8080).run()
```

The 'app' package should contain the agents and tools (see below). <br>
You can define sub-packages to organize your agents and tools (you must define the __init__.py file in each package). At the server start, the server will automatically discover all agents and tools.<br>
Run the app with:

```
python main.py
```

The app will start by default on "[http://localhost:8080](http://localhost:8080)".<br>
You can see the APIs documentation at "[http://localhost:8080/docs](http://localhost:8080/docs)".

## A2A

### Define an Agent:

Create the hello_agent.py file with the following content:

```python
from agentic.a2a.core import agent, skill, BaseAgent
from a2a.server.agent_execution import RequestContext
from a2a.utils import new_agent_text_message
from a2a.server.events import Event

@agent(
    description="Hello World Agent",
)
class HelloAgent(BaseAgent):

    async def execute(self, input:RequestContext) -> Event:
        out = new_agent_text_message("Hello World!")
        return out

    @skill(
        name="say_hello", 
        description="Say hello to someone by name",
    )
    async def say_hello(self, name):
        ...
        return "Hello " + name + "!"
```

### Use the A2A Client:

To test the server, you can use the A2A client. Here's an example of how to use the client to interact with the server:

```python
import asyncio
from agentic.a2a.client import ClientA2A
from agentic.a2a.utility import ResponseParser
from a2a.types import DataPart

async def main():
    client = ClientA2A(url='http://localhost:8080')

    data = { "messages": [
            {'role': 'user', 'content': 'Hello!'},
    ]}
    
    result = await client.invoke("/helloagent", parts=[DataPart(data=data)])
    parser = ResponseParser(result)
    print("RESULT: ", parser.get_parts())

if __name__ == "__main__":
    asyncio.run(main())
```

## MCP

### Define an MCP Tool:

Create the hello_tool.py file with the following content:

```python
from agentic.mcp.core import mcp

@mcp(
    methods=["GET"],
    tags=["hello"],
    path="/hello/{name}",
)
def hello_world(name:str) -> str:
    """ Hello World MCP tool """
    return "Hello, " + name + "!"
```

### Integration with external MCP client:

The MCP server can be integrated with any MCP client such as [Cloude Desktop](https://claude.ai/download).
To connect the client with the remote server you need to use mcp-proxy.
To install the proxy you can use uv:

```
uv tool install mcp-proxy
```

Below is an example for claude_desktop_config.json:

```json
{
    "mcpServers": {
        "mytool": {
            "command": "uv",
            "args": ["tool", "run", "mcp-proxy", "http://localhost:8080/mcp"]
        }
    }
}
```

## Contributing

As this is a beta project, contributions are especially welcome! Please feel free to:
- Report bugs and issues
- Suggest new features
- Submit pull requests
- Provide feedback on the API design

## Links

### Tutorials
- [Agentic Framework - Develop MCP Tools in Python](https://www.devturtleblog.com/agentic-a2a-framework-mcp/)

### Related fonts
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [A2A Python SDK](https://github.com/google-a2a/a2a-python)
- [FastAPI MCP](https://github.com/tadata-org/fastapi_mcp)
- [Agent-to-Agent Protocol Specification](https://github.com/google-a2a)
- [MCP protocol](https://modelcontextprotocol.io/introduction)
