File size: 3,206 Bytes
854a4a5
 
 
 
 
 
25b5ce3
854a4a5
d073ade
854a4a5
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
---
title: Python-Agent
emoji: ๐Ÿค–
colorFrom: blue
colorTo: green
sdk: gradio
app_file: app.py  # <--- ๆทปๅŠ ่ฟ™ไธ€่กŒ๏ผŒๆŒ‡ๅฎšๅฏๅŠจๆ–‡ไปถ
pinned: false
paused: true
---


# Python Agent

A modular Python-based AI agent service built with FastAPI, integrating **Nacos** for service discovery and **Model Context Protocol (MCP)** for extensible tool usage. This agent uses **LangGraph** to orchestrate agentic workflows.

## Features

- **FastAPI Framework**: High-performance, easy-to-learn web framework.
- **Service Discovery**: Seamless integration with Nacos for service registration and discovery.
- **LangGraph**: Stateful, multi-actor applications with cycles (agentic orchestration).
- **Model Context Protocol (MCP)**:
    - **Stdio Client**: Connects to local CLI tools (e.g., Brave Search via Node.js).
    - **SSE Client**: Connects to remote services (e.g., Java backend) via Server-Sent Events.

## Prerequisites

- **Python 3.10+**
- **Node.js**: Required for running the Brave Search MCP server (`npx`).
- **Nacos Server 2.x**: A running Nacos instance is required for the application to start.

## Installation

1. Clone the repository:
   ```bash
   git clone <repository_url>
   cd python-agent
   ```

2. Create and activate a virtual environment:
   ```bash
   python -m venv .venv
   # Windows
   .venv\Scripts\activate
   # Linux/Mac
   source .venv/bin/activate
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Configuration

The application is configured via environment variables. You can create a `.env` file in the root directory (see `.env.example`).

| Variable | Default | Description |
|----------|---------|-------------|
| `APP_ENV` | `development` | Application environment (`development` or `production`). |
| `HOST` | `0.0.0.0` | Host to bind the server to. |
| `PORT` | `8181` | Port to listen on. |
| `NACOS_SERVER_ADDR` | `` | Address of the Nacos server. |
| `NACOS_NAMESPACE` | `public` | Nacos namespace ID. |
| `NACOS_USERNAME` | `` | Nacos username. |
| `NACOS_PASSWORD` | `` | Nacos password. |
| `SERVICE_NAME` | `python-agent` | Name of this service in Nacos. |
| `MCP_BRAVE_PATH` | (Auto-detected) | Optional override for `npx` path. |
| `NACOS_GATEWAY_SERVICE_NAME` | `gateway` | Name of the Java/Gateway service to discover. |

## Usage

### Running the Application

Using `python`:
```bash
python main.py
```

Using `uvicorn` (with hot reload):
```bash
uvicorn main:app --reload --port 8181
```

> **Note**: The application will fail to start if it cannot connect to the configured Nacos server.

### API Endpoints

- **Health Check**: `GET /health`
- **Chat**: `POST /chat`
    ```json
    {
      "message": "Search for the latest news on AI."
    }
    ```

## Project Structure

The project follows a modular package structure:

```text
python-agent/
โ”œโ”€โ”€ app/
โ”‚   โ”œโ”€โ”€ core/           # Core configuration & infrastructure (Nacos, Config)
โ”‚   โ”œโ”€โ”€ services/       # External service clients (MCP)
โ”‚   โ”œโ”€โ”€ agent/          # LangGraph logic (State, Graph, Nodes)
โ”‚   โ””โ”€โ”€ setup.py        # Startup setup scripts
โ”œโ”€โ”€ main.py             # Entry point
โ””โ”€โ”€ ...
```