README.md

---
title: Process-Aware LangGraph Agent
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.42.0
app_file: app.py
pinned: false
python_version: 3.12
---

# Process-Aware LangGraph Agent

# LangGraph Process Management Agent

A LangGraph agentic project for process management and execution guidance. The agent is a specialized **Process Management Assistant** whose behavior is defined through markdown files, including imperative process descriptions and normative constraints.

## 📁 Project Structure

```
langgraph_agent/
├── agents/              # Agent implementations
│   ├── __init__.py
│   └── process_aware_agent.py  # Process-aware agent logic
├── config/              # Configuration management
│   ├── __init__.py
│   └── settings.py      # Settings and environment variables
├── docs/                # Agent definitions (markdown)
│   ├── agent_definition.md      # Agent behavior and prompts
│   ├── graph_structure.md       # Graph architecture documentation
│   ├── process-description.md   # Imperative process description
│   └── process-constraints.md   # Normative process constraints
├── tools/               # Custom tools (empty for now)
├── utils/               # Utility functions
│   ├── __init__.py
│   └── markdown_loader.py     # Load agent definitions from markdown
├── .env.example         # Example environment variables
├── example.py           # Example usage scripts
├── main.py              # Main entry point for interactive mode
├── pyproject.toml       # Project metadata and dependencies
└── requirements.txt     # Python dependencies
```

## 🚀 Getting Started

### Prerequisites

- Python 3.10 or higher
- OpenAI API key

### Installation

1. **Clone or navigate to the project directory:**
   ```bash
   cd langgraph_agent
   ```

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

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

4. **Set up environment variables:**
   ```bash
   cp .env.example .env
   ```
   
   Edit `.env` and add your OpenAI API key:
   ```
   OPENAI_API_KEY=your_actual_api_key_here
   ```

## 💻 Usage

### Interactive Mode

Run the agent in interactive chat mode:

```bash
cd langgraph_agent
python main.py
```

This starts an interactive session where you can chat with the agent. Type `exit` or `quit` to end.

### Single Query Mode

Run a single query from the command line:

```bash
cd langgraph_agent
python main.py "Describe the business process you are managing."
```

### Example Scripts

Run the example scripts to see different usage patterns:

```bash
cd langgraph_agent
python example.py
```

This demonstrates:
- Simple single-turn queries
- Multi-turn conversations with context
- Custom agent definitions
- Tool usage (text summarization)

## 📝 Customizing the Agent

### Agent Role: Process Management Assistant

The agent is designed as a **Process Management Assistant** that:
- Provides information about business processes
- Guides users through process execution
- Ensures compliance with normative constraints
- Requests permission for deviations from standard flows
- Always adheres to mandatory process rules

### Modify Agent Behavior

Edit `docs/agent_definition.md` to customize:
- Agent name and role
- System prompt
- Capabilities
- Behavior guidelines
- Example interactions

### Define Your Process

#### 1. Process Description (`docs/process-description.md`)

This file contains the **imperative process description** - the typical way the process should flow.

**Current Process**: Purchase-to-Pay / Procurement Exception-Handling Process

The process manages the complete lifecycle of procurement documents with integration to SRM (Supplier Relationship Management) and execution systems. It includes:

- **44 activities** covering:
  - SRM status management (Created, Ordered, Complete, Awaiting Approval, Held, etc.)
  - Procurement creation and release (requisitions and purchase orders)
  - Logistics and fulfillment (goods receipts, service entry sheets, invoices)
  - Extensive change and correction activities (quantity, price, currency, payment terms, delivery, storage location)

- **Main Flow**:
  1. Start → SRM status handling
  2. Create Purchase Requisition Item → Release Purchase Requisition
  3. Create Purchase Order Item → Release Purchase Order
  4. Transfer to execution system
  5. Vendor confirmation and fulfillment (order confirmation, goods receipt, invoice)
  6. Change handling and reprocessing (supports post-order corrections)
  7. Completion and closure

- **Decision Points**: Extensive use of exclusive and parallel gateways for document state management, approval routing, transfer success/failure, and correction paths

The agent has autonomy to guide execution according to this description, as long as it conforms to the normative constraints.

#### 2. Process Constraints (`docs/process-constraints.md`)

This file contains **normative constraints** - strict rules that must NEVER be violated.

**Current Constraints**: Declare Constraints for Purchase Order Process

Key constraints include:

- **Existence Constraints**:
  - Create Purchase Order Item must occur exactly once
  - Record Goods Receipt must occur exactly once

- **Initialization**:
  - Create Purchase Order Item must be the first activity

- **Response Constraints**:
  - Creating a purchase order triggers eventual goods receipt recording
  - Purchase order creation must be followed by goods receipt

- **Precedence Constraints**:
  - Goods receipt can only occur after purchase order creation
  - Purchase order must always precede goods receipt

- **Negative Constraints** (Forbidden Patterns):
  - Cannot create purchase order after goods receipt
  - Cannot have direct succession of goods receipt → purchase order creation
  - Purchase order creation must NOT follow goods receipt recording

**Important**: The agent will ALWAYS conform to these constraints. When execution needs to deviate from the typical flow in `process-description.md`, the agent will ask for permission, but only in ways that still satisfy all constraints in `process-constraints.md`.

### How the Agent Uses Process Specifications

1. **Process Knowledge**: The agent has complete knowledge of both the process description and constraints
2. **Execution Guidance**: It guides users through the process according to the typical flow
3. **Constraint Adherence**: It NEVER violates normative constraints
4. **Deviation Management**: When deviations from the typical flow are needed, it asks permission first
5. **Compliance First**: All suggestions and actions must conform to the normative constraints

The agent will automatically load these process specifications on startup and integrate them into its decision-making.

### Create Multiple Agents

1. Create a new markdown file in `docs/` (e.g., `docs/specialist_agent.md`)
2. Define the agent's behavior using the same structure as `agent_definition.md`
3. Load it in your code:

```python
from pathlib import Path
from agents.process_aware_agent import run_agent

response = run_agent(
    "Your query here",
    agent_definition_path=Path("docs/specialist_agent.md")
)
```

## 🏗️ Architecture

### LangGraph Structure

The agent uses a graph with conditional tool execution:

```
START → Agent Node → [Tool Node] → Agent Node → END
                ↓
               END
```

The agent can:
1. Respond directly for simple queries
2. Call tools when needed (e.g., summarization)
3. Process tool results and provide final response

### Available Tools

**summarize_text**: Summarizes long text into concise summaries
- Takes text input and optional max_sentences parameter
- Returns a brief summary of the input
- Automatically invoked when user requests summarization

### State Management

The graph maintains:
- **messages**: Conversation history
- **agent_name**: Active agent identifier
- **metadata**: Additional context

## 🔧 Configuration

Configuration is managed through environment variables and `config/settings.py`:

- `OPENAI_API_KEY`: Your OpenAI API key (required)
- `OPENAI_MODEL`: Model to use (default: gpt-4o-mini)
- `TEMPERATURE`: LLM temperature (default: 0.7)
- `MAX_TOKENS`: Maximum response tokens (default: 1000)

Optional LangSmith tracing:
- `LANGCHAIN_TRACING_V2`: Enable tracing (default: false)
- `LANGCHAIN_API_KEY`: LangSmith API key
- `LANGCHAIN_PROJECT`: Project name

## 📚 Key Components

### Agent Definition Loader (`utils/markdown_loader.py`)

Parses markdown files to extract:
- Agent name and role
- System prompts
- Behavior guidelines
- Example interactions

### Process-Aware Agent (`agents/process_aware_agent.py`)

Core agent implementation:
- `create_agent_graph()`: Creates a LangGraph instance with process specifications
- `run_agent()`: Convenience function for single queries
- Automatically loads process description and constraints
- Integrates process context into system prompt

### Settings (`config/settings.py`)

Manages configuration using Pydantic settings:
- Environment variable loading
- Type validation
- Default values

## 🛠️ Development

### Adding Tools

The project includes a text summarization tool. To add more tools:

1. Create tool functions in `tools/` using the `@tool` decorator:
   ```python
   from langchain_core.tools import tool
   
   @tool
   def your_tool(param: str) -> str:
       """Tool description."""
       # Implementation
       return result
   ```

2. Import and add to the tools list in `agents/process_aware_agent.py`:
   ```python
   from tools.your_tool import your_tool
   tools = [summarize_text, your_tool]
   ```

3. Update `docs/agent_definition.md` to document the new tool

### Extending the Graph

To add more complex workflows:

1. Define additional nodes in your agent file
2. Add conditional edges for routing logic
3. Update `docs/graph_structure.md` to document changes

## 📖 Further Reading

- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
- [LangChain Documentation](https://python.langchain.com/)
- [OpenAI API Documentation](https://platform.openai.com/docs/)

## 📄 License

This project is provided as-is for educational and development purposes.

## 🤝 Contributing

Feel free to extend and modify this project structure for your needs!