diff --git a/Makefile b/Makefile index fab1a46..eabf159 100644 --- a/Makefile +++ b/Makefile @@ -39,6 +39,9 @@ setup-temporal-mac: brew install temporal temporal server start-dev +make start-temporal-server: + temporal server start-dev + # Run all development services run-dev: @echo "Starting all development services..." @@ -60,4 +63,4 @@ help: @echo " make run-legacy-worker - Start the legacy worker" @echo " make run-enterprise - Build and run the enterprise .NET worker" @echo " make setup-temporal-mac - Install and start Temporal server on Mac" - @echo " make run-dev - Start all development services (worker, API, frontend) in parallel" \ No newline at end of file + @echo " make run-dev - Start all development services (worker, API, frontend) in parallel" diff --git a/activities/tool_activities.py b/activities/tool_activities.py index 1380666..4317260 100644 --- a/activities/tool_activities.py +++ b/activities/tool_activities.py @@ -40,10 +40,13 @@ def __init__(self, mcp_client_manager: MCPClientManager = None): self.llm_model = os.environ.get("LLM_MODEL", "openai/gpt-4") self.llm_key = os.environ.get("LLM_KEY") self.llm_base_url = os.environ.get("LLM_BASE_URL") + self.llm_provider = os.environ.get("LLM_PROVIDER") self.mcp_client_manager = mcp_client_manager print(f"Initializing ToolActivities with LLM model: {self.llm_model}") if self.llm_base_url: print(f"Using custom base URL: {self.llm_base_url}") + if self.llm_provider: + print(f"Using LLM provider: {self.llm_provider}") if self.mcp_client_manager: print("MCP client manager enabled for connection pooling") @@ -134,6 +137,8 @@ async def agent_toolPlanner(self, input: ToolPromptInput) -> dict: if self.llm_base_url: completion_kwargs["base_url"] = self.llm_base_url + if self.llm_provider: + completion_kwargs["provider"] = self.llm_provider response = completion(**completion_kwargs) response_content = response.choices[0].message.content diff --git a/notes/README.md b/notes/README.md new file mode 100644 index 0000000..f19eb10 --- /dev/null +++ b/notes/README.md @@ -0,0 +1,57 @@ +# Learning Journey: Temporal AI Agent Experiments + +This directory contains my personal notes, experiments, and learnings while exploring the Temporal AI Agent system. The goal is to understand how to effectively use agentic systems within Temporal's durable workflow model. + +## Directory Structure + +- [`experiments/`](./experiments/): Detailed documentation of specific experiments and tests + - Each experiment is numbered for easy reference + - Contains setup, observations, and results + +- [`learnings/`](./learnings/): Key concepts and patterns discovered + - Temporal concepts + - Agent patterns + - Challenges and solutions + +- [`resources/`](./resources/): Useful references and links + - External documentation + - Relevant articles + - Community discussions + +## Quick Start + +The experiments are numbered sequentially (001, 002, etc.) and can be found in the `experiments/` directory. Each experiment includes: +- Objective +- Setup instructions +- Code changes/additions +- Results and observations +- Learnings and takeaways + +## Key Topics + +1. Temporal Workflows with AI Agents +2. Agent-based Decision Making +3. Durable Execution Patterns +4. Error Handling and Recovery +5. Testing and Debugging Strategies + +## Progress Tracking + +- [ ] Basic workflow setup and execution +- [ ] Agent integration and configuration +- [ ] Complex decision-making scenarios +- [ ] Error handling and recovery patterns +- [ ] Performance optimization +- [ ] Production-ready considerations + +## Notes + +- This is a learning repository forked from the original temporal-ai-agent demo +- These notes are personal and reflect my learning journey +- Feel free to adapt and modify the structure as needed + +## References + +- [Original Repository](https://github.com/temporalio/temporal-ai-agent) +- [Temporal Documentation](https://docs.temporal.io/) +- [AI Agent Documentation](./docs/README.md) \ No newline at end of file diff --git a/notes/experiments/000-run-tests.md b/notes/experiments/000-run-tests.md new file mode 100644 index 0000000..d38d655 --- /dev/null +++ b/notes/experiments/000-run-tests.md @@ -0,0 +1,24 @@ +# Experiment 000 - Run Tests +## Objective +- Run tests for the Temporal AI Agent project + +## Steps +1. Install poetry if not already installed +`brew install poetry` +2. Install development dependencies +`poetry install --with dev` +2. Run the tests `poetry run pytest` + +## Issues and fixes + +### No module named pytest_asyncio +**Error** +``` +ImportError while loading conftest '/Users/joeszodfridt/src/temporal/temporal-ai-agent/tests/conftest.py'. +tests/conftest.py:7: in + import pytest_asyncio +E ModuleNotFoundError: No module named 'pytest_asyncio' +``` +**Remediation** +- Install development dependencies +`poetry install --with dev` diff --git a/notes/experiments/001-basic-workflow.md b/notes/experiments/001-basic-workflow.md new file mode 100644 index 0000000..881831d --- /dev/null +++ b/notes/experiments/001-basic-workflow.md @@ -0,0 +1,87 @@ +# Experiment 001: Setup and run locally out of the box demo + +**Date**: + +## Objective +To understand what's involved in setting up and running the Temporal AI Agent locally out of the box demo. + +## Setup + +### Environment +- Local development environment + - I'm using asdf (already installed)to manage python versions + - Temporal is already installed using brew, `brew install temporal` + +- Temporal server running + - Start server using make commands: `make start-temporal-server ` + +### Configuration +Copy `.env.example` to `.env` and configure +- Set `LLM_KEY=YOUR_API_KEY` +- Set `LLM_MODEL=YOUR_MODEL_NAME`, e.g `anthropic/claude-3-5-sonnet-20240620` +- Set `STRIPE_API_KEY=` to generate mock data, use your Stripe API key if you have one + + +## Implementation Steps + +Start local Temporal server +`make start-temporal-server` + +Start api, workers, workflow and UI +`make run-dev` + +Temporal workflow monitor +- URL is displayed in the output when server is started + +Application UI + + +## Observations + +### What Worked Well +- Demo runs when using Antrhopic and my personal key. NF key is always out of capacity +- Demo fails when running with Ollama locally. Will need some code changes to support Ollama + +### Challenges Encountered +- Challenge 1 + - Solution/Workaround: +- Challenge 2 + - Solution/Workaround: + +## Key Learnings + +1. Learning 1 + - Details... +2. Learning 2 + - Details... + +## Questions to Explore +- [ ] Question 1 +- [ ] Question 2 + +## Next Steps +- [ ] What to try next +- [ ] Areas to improve + +## Resources Used +- Link 1 +- Link 2 + +## Code Snippets and Examples + +### Example 1: Description +```python +# Add example code here +``` + +### Example 2: Description +```python +# Add example code here +``` + +## Notes for Future Reference +- Important note 1 +- Important note 2 + +--- +Last Updated: diff --git a/notes/experiments/002-basic-workflow-groq.md b/notes/experiments/002-basic-workflow-groq.md new file mode 100644 index 0000000..eca96eb --- /dev/null +++ b/notes/experiments/002-basic-workflow-groq.md @@ -0,0 +1,73 @@ +# Experiment 002: Run basic demo using Groq models + +**Date**: 6/26/25 + +## Objective +Get the out of the box demo using Groq for LLM models + + +## Setup + +### Environment +- Same as in basic workflow no changes + +### Configuration +- Uncomment the Groq LLM configuration in .env + +## Implementation Steps +- Start temporal server: `make start-temporal-server` +- Start the apis, workers, etc.: `make run-dev` +- Run the demo + +## Observations +- Groq is fast!!! +- Quickly burn through the free tokens as Groq is rate limiting my free plan requests +- The demo handles the rate limit without crashing +- Workflow will timeout gracefully after 30 minutes, and app will stay alive +- Demo doesn't have any messaging about service provider hitting rate limiting + +### What Worked Well + +### Challenges Encountered +- Challenge 1 + - Solution/Workaround: +- Challenge 2 + - Solution/Workaround: + +## Key Learnings + +1. Learning 1 + - Details... +2. Learning 2 + - Details... + +## Questions to Explore +- [ ] Question 1 +- [ ] Question 2 + +## Next Steps +- [ ] What to try next +- [ ] Areas to improve + +## Resources Used +- Link 1 +- Link 2 + +## Code Snippets and Examples + +### Example 1: Description +```python +# Add example code here +``` + +### Example 2: Description +```python +# Add example code here +``` + +## Notes for Future Reference +- Important note 1 +- Important note 2 + +--- +Last Updated: diff --git a/notes/experiments/experiment-template.md b/notes/experiments/experiment-template.md new file mode 100644 index 0000000..b7c6983 --- /dev/null +++ b/notes/experiments/experiment-template.md @@ -0,0 +1,65 @@ +# Experiment 000: Title + +**Date**: + +## Objective + + +## Setup + +### Environment + + +### Configuration + + +## Implementation Steps + + +## Observations + +### What Worked Well + +### Challenges Encountered +- Challenge 1 + - Solution/Workaround: +- Challenge 2 + - Solution/Workaround: + +## Key Learnings + +1. Learning 1 + - Details... +2. Learning 2 + - Details... + +## Questions to Explore +- [ ] Question 1 +- [ ] Question 2 + +## Next Steps +- [ ] What to try next +- [ ] Areas to improve + +## Resources Used +- Link 1 +- Link 2 + +## Code Snippets and Examples + +### Example 1: Description +```python +# Add example code here +``` + +### Example 2: Description +```python +# Add example code here +``` + +## Notes for Future Reference +- Important note 1 +- Important note 2 + +--- +Last Updated: diff --git a/notes/learnings/temporal-concepts.md b/notes/learnings/temporal-concepts.md new file mode 100644 index 0000000..c577cb1 --- /dev/null +++ b/notes/learnings/temporal-concepts.md @@ -0,0 +1,135 @@ +# Temporal Core Concepts + +This document captures key concepts and learnings about Temporal's architecture and programming model. + +## Core Concepts + +### 1. Workflows +- Definition: Long-running, reliable business logic +- Key characteristics: + - [ ] Durability + - [ ] Determinism + - [ ] History and state management + - [ ] Error handling + +### 2. Activities +- Definition: Individual tasks that workflows orchestrate +- Key characteristics: + - [ ] Idempotency considerations + - [ ] Retry policies + - [ ] Heartbeat mechanics + - [ ] Activity timeouts + +### 3. Workers +- Definition: Service processes that execute workflow and activity code +- Key points: + - [ ] Task queues + - [ ] Worker options + - [ ] Resource management + - [ ] Sticky execution + +### 4. Task Queues +- Purpose and usage +- Load balancing +- Worker assignment + +## Durable Execution Patterns + +### 1. State Management +- [ ] How Temporal manages workflow state +- [ ] Best practices for state handling +- [ ] Dealing with non-deterministic changes + +### 2. Error Handling +- [ ] Retry policies +- [ ] Timeouts +- [ ] Compensation logic +- [ ] Error propagation + +### 3. Testing Strategies +- [ ] Unit testing workflows +- [ ] Testing activities +- [ ] Integration testing +- [ ] Temporal testing framework + +## Integration with AI Agents + +### 1. Agent State Management +- [ ] Persisting agent state +- [ ] Handling large context windows +- [ ] Memory management patterns + +### 2. Decision Making +- [ ] Deterministic agent decisions +- [ ] Handling non-deterministic AI responses +- [ ] Validation and safety checks + +### 3. Error Handling +- [ ] AI service failures +- [ ] Invalid responses +- [ ] Timeout handling +- [ ] Retry strategies + +## Advanced Concepts + +### 1. Saga Pattern +- [ ] Understanding compensating transactions +- [ ] Implementation patterns +- [ ] Error handling in distributed transactions + +### 2. Child Workflows +- [ ] Parent-child relationships +- [ ] Data passing +- [ ] Error propagation +- [ ] Monitoring and observability + +### 3. Signal Handling +- [ ] External events +- [ ] State updates +- [ ] Coordination patterns + +## Performance Considerations + +### 1. Optimization Techniques +- [ ] Caching strategies +- [ ] Resource utilization +- [ ] Parallel execution +- [ ] Batch processing + +### 2. Monitoring and Debugging +- [ ] Metrics collection +- [ ] Logging practices +- [ ] Debugging tools +- [ ] Performance profiling + +## Resources + +### Official Documentation +- [ ] Link to core concepts +- [ ] Link to best practices +- [ ] Link to patterns + +### Community Resources +- [ ] Useful blog posts +- [ ] Conference talks +- [ ] Sample applications + +## Personal Notes and Insights + +### Learned Patterns +1. Pattern 1 + - Description + - Use cases + - Examples + +### Anti-patterns to Avoid +1. Anti-pattern 1 + - Why it's problematic + - Better alternatives + +### Questions to Explore +- [ ] Question 1 +- [ ] Question 2 + +--- +Last Updated: diff --git a/notes/resources/useful-links.md b/notes/resources/useful-links.md new file mode 100644 index 0000000..6038c36 --- /dev/null +++ b/notes/resources/useful-links.md @@ -0,0 +1,101 @@ +# Useful Resources and Links + +A curated collection of resources for working with Temporal and AI Agents. + +## Official Documentation + +### Temporal +- [Temporal Documentation](https://docs.temporal.io/) +- [Temporal Python SDK](https://python.temporal.io/) +- [Temporal TypeScript SDK](https://typescript.temporal.io/) +- [Temporal Architecture](https://docs.temporal.io/dev-guide/temporal-explained) +- [Temporal Patterns](https://docs.temporal.io/dev-guide/patterns) + +### AI and LLM Resources +- [OpenAI API Documentation](https://platform.openai.com/docs/) +- [LangChain Documentation](https://python.langchain.com/docs/get_started/introduction) +- [Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) + +## Learning Resources + +### Temporal Tutorials and Guides +- [Temporal Python Tutorial](https://learn.temporal.io/tutorials/python/) +- [Getting Started with Temporal](https://learn.temporal.io/getting_started/) +- [Temporal YouTube Channel](https://www.youtube.com/temporalio) +- [Temporal Blog](https://temporal.io/blog) + +### AI Agent Development +- [LangChain AI Handbook](https://www.pinecone.io/learn/langchain/) +- [Building AI Agents](https://www.davidbaker.dev/posts/ai-agents-how-to-build/) +- [ReAct Pattern](https://www.promptingguide.ai/techniques/react) +- [AutoGPT Documentation](https://docs.agpt.co/) + +## Community Resources + +### Temporal Community +- [Temporal Community Forums](https://community.temporal.io/) +- [Temporal Discord](https://discord.com/invite/temporal) +- [Temporal GitHub](https://github.com/temporalio) +- [Temporal Stack Overflow](https://stackoverflow.com/questions/tagged/temporal-workflow) + +### AI Development Communities +- [r/LocalLLaMA](https://www.reddit.com/r/LocalLLaMA/) +- [HuggingFace Forums](https://discuss.huggingface.co/) +- [LangChain Discord](https://discord.com/invite/6adMQxSpJS) + +## Example Projects and References + +### Temporal Examples +- [Temporal Samples Repository](https://github.com/temporalio/samples-python) +- [Temporal Money Transfer Example](https://github.com/temporalio/money-transfer-project-template-python) +- [Temporal Subscription Workflow](https://github.com/temporalio/subscription-workflow-project-template-python) + +### AI Agent Examples +- [BabyAGI](https://github.com/yoheinakajima/babyagi) +- [AutoGPT](https://github.com/Significant-Gravitas/Auto-GPT) +- [LangChain Examples](https://github.com/langchain-ai/langchain/tree/master/examples) + +## Tools and Utilities + +### Development Tools +- [Temporal CLI](https://docs.temporal.io/cli) +- [Temporal Web UI](https://docs.temporal.io/web-ui) +- [tctl (Temporal Command-Line Tool)](https://docs.temporal.io/tctl) + +### AI Development Tools +- [LangSmith](https://www.langchain.com/langsmith) +- [Weights & Biases](https://wandb.ai/) +- [OpenAI Playground](https://platform.openai.com/playground) + +## Articles and Blog Posts + +### Temporal Best Practices +- [Temporal Anti-Patterns](https://temporal.io/blog/temporal-anti-patterns) +- [Testing Temporal Workflows](https://docs.temporal.io/dev-guide/python/testing) +- [Handling Failures in Temporal](https://temporal.io/blog/handling-failures-in-temporal) + +### AI Agent Architecture +- [Emerging Architectures for LLM Applications](https://a16z.com/emerging-architectures-for-llm-applications/) +- [AI Agents Architecture Patterns](https://eugeneyan.com/writing/ai-agents/) +- [Building Reliable AI Systems](https://newsletter.theaiguys.dev/p/building-reliable-ai-systems) + +## Papers and Research + +### AI Agents +- [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629) +- [Task-driven Autonomous Agent](https://arxiv.org/abs/2303.17760) +- [Large Language Models as Tool Makers](https://arxiv.org/abs/2305.17126) + +--- + +## Notes and Updates + +### Recent Additions +- Add new resources here... + +### To Review +- [ ] New frameworks to evaluate +- [ ] Interesting articles to read +- [ ] Tools to try out + +Last Updated: [Date] \ No newline at end of file