# How to Integrate Your Own AI Agent with ai-agents-for-beginners: A Complete Guide

> Integrate your AI agent with microsoft/ai-agents-for-beginners. Follow this guide to configure credentials, create agents, define tools, and start your custom AI project today.

- Repository: [Microsoft/ai-agents-for-beginners](https://github.com/microsoft/ai-agents-for-beginners)
- Tags: how-to-guide
- Published: 2026-04-22

---

**You can integrate your own AI agent with microsoft/ai-agents-for-beginners by following the repository's standard pattern: configure Azure credentials, create an `AzureAIProjectAgentProvider`, define custom tools with the `@tool` decorator, and instantiate your agent with a system prompt.**

The **AI Agents for Beginners** repository provides a structured learning path for building AI agents using the **Microsoft Agent Framework (MAF)** and Azure AI Foundry. Each lesson follows a consistent pattern that you can replicate to plug in your own custom agent logic. This guide walks through the exact integration steps, complete with file references from the source code and production-ready code examples.

## Prerequisites and Environment Setup

Before integrating your custom agent, you need to establish the foundational Azure authentication and package dependencies.

### Install Required Packages

The repository relies on three core packages that handle agent orchestration, Azure service integration, and authentication:

```python

# Run in your notebook or terminal

!pip install agent-framework azure-ai-projects azure-identity -q

```

### Configure Azure Credentials

The Microsoft Agent Framework authenticates through Azure AI Foundry. You must expose two environment variables that point to your deployed model:

```bash

# Sign in via Azure CLI

az login

# Set environment variables (copy from .env.example)

export AZURE_AI_PROJECT_ENDPOINT="https://<your-resource>.openai.azure.com/"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o"

```

The repository provides a template configuration in [`.env.example`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/.env.example) that you can copy and customize for your deployment.

## Create the AzureAIProjectAgentProvider

The `AzureAIProjectAgentProvider` serves as the authentication gateway and agent factory for all operations in the repository. This pattern appears in every lesson's code samples.

```python
from agent_framework.azure import AzureAIProjectAgentProvider
from azure.identity import AzureCliCredential

# Authenticates to Azure AI Foundry and creates agent instances

provider = AzureAIProjectAgentProvider(credential=AzureCliCredential())

```

This provider instantiation appears in [`01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb) at lines 64-69, establishing the pattern used throughout the repository.

## Define Custom Tools with the @tool Decorator

The Microsoft Agent Framework converts any Python function into a callable tool through the `@tool` decorator. This is where you integrate your custom business logic.

### Basic Tool Structure

```python
from typing import Annotated
from agent_framework import tool

@tool(approval_mode="never_require")
def fetch_customer_balance(
    customer_id: Annotated[str, "The unique ID of the customer"]
) -> str:
    """Return account balance for the specified customer."""
    # Replace with actual database query or API call

    return f"${int(customer_id[-2:]) * 123.45:,.2f}"

```

The repository demonstrates this pattern in [`01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb) at lines 93-100, showing a travel destination lookup tool.

### Tool Integration Options

Your custom tools can connect to virtually any backend system:

| Integration Type | Example Implementation |
|------------------|------------------------|
| Database queries | SQLAlchemy or raw SQL calls |
| External APIs | `requests` or `httpx` for REST, `grpc` for RPC |
| Vector search | Azure AI Search, Pinecone, or Chroma integration |
| Custom calculations | Python business logic, ML model inference |
| File operations | Local or cloud storage (Azure Blob, S3) |

## Instantiate Your Custom Agent

With the provider and tools defined, you create your agent by combining these components with a system prompt that defines its behavior.

```python

# Create the agent with custom tools and instructions

agent = await provider.create_agent(
    tools=[fetch_customer_balance],
    name="FinanceAssistant",
    instructions=(
        "You are a helpful finance assistant. When a user asks about their balance, "
        "call the fetch_customer_balance tool with the supplied customer ID. "
        "Present the result clearly and offer additional assistance."
    ),
)

```

This agent creation pattern appears in [`01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb) at lines 17-30, demonstrating the travel agent instantiation.

## Execute and Run Your Agent

The Microsoft Agent Framework supports both synchronous responses and streaming output for interactive applications.

### Synchronous Execution

```python

# Single-turn response

user_message = "What's the balance for customer 42?"
response = await agent.run(user_message)
print("Agent reply:", response)

```

### Streaming for Chat Interfaces

```python

# Token-by-token streaming for real-time UI updates

async for chunk in agent.run(
    "Give me a summary of my last three transactions",
    stream=True
):
    print(chunk, end="", flush=True)

```

Streaming support enables responsive chat applications without waiting for complete generation.

## Add Production Patterns from Lesson 10

The repository's production lesson provides essential patterns for production deployments. These augment your basic agent with observability, evaluation, and cost management.

### Simple Timing Observability

```python
import time

start = time.time()
response = await agent.run("What's the balance for customer 42?")
elapsed = time.time() - start
print(f"Response ({elapsed:.2f}s): {response}")

```

### Evaluator Agent Pattern

The production lesson demonstrates using a secondary agent to evaluate responses:

```python

# Create evaluator agent with scoring rubric

evaluator = await provider.create_agent(
    name="ResponseEvaluator",
    instructions="""
    You evaluate finance-assistant replies on:
    1. Completeness (1-5) – does it include the balance?
    2. Accuracy (1-5) – is the number realistic?
    3. Helpfulness (1-5) – is the tone appropriate?
    4. Overall (1-5)
    Return a short JSON object with the scores.
    """,
)

# Score the primary agent's response

evaluation = await evaluator.run(
    f"Evaluate this response:\n\n{response}"
)
print("Evaluation:", evaluation)

```

This pattern appears in [`10-ai-agents-production/code_samples/10-python-agent-framework.ipynb`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/10-ai-agents-production/code_samples/10-python-agent-framework.ipynb) at lines 67-75, with timing instrumentation at lines 36-42.

## Leverage Advanced Patterns from Other Lessons

Once your basic integration works, you can incorporate additional patterns from the repository's specialized lessons:

| Lesson | Pattern | File Reference |
|--------|---------|----------------|
| 14 - Sequential Workflows | Chain multiple agents for multi-step pipelines | [`14-microsoft-agent-framework/code-samples/14-sequential.ipynb`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/14-microsoft-agent-framework/code-samples/14-sequential.ipynb) |
| 05 - Agentic RAG | Integrate retrieval-augmented generation for knowledge bases | [`05-agentic-rag/code_samples/05-python-agent-framework.ipynb`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/05-agentic-rag/code_samples/05-python-agent-framework.ipynb) |
| 10 - Production | Observability, evaluation, and cost management | [`10-ai-agents-production/code_samples/10-python-agent-framework.ipynb`](https://github.com/microsoft/ai-agents-for-beginners/blob/main/10-ai-agents-production/code_samples/10-python-agent-framework.ipynb) |

These patterns compose with your custom agent—you can mix sequential workflows with your custom tools, or add RAG retrieval to your agent's capabilities.

## Summary

To integrate your own AI agent with **ai-agents-for-beginners**, follow this proven pattern from the repository:

- **Install dependencies**: `agent-framework`, `azure-ai-projects`, and `azure-identity`
- **Authenticate**: Use `AzureCliCredential` with `AZURE_AI_PROJECT_ENDPOINT` and `AZURE_AI_MODEL_DEPLOYMENT_NAME` environment variables
- **Create the provider**: Instantiate `AzureAIProjectAgentProvider` as your agent factory
- **Define custom tools**: Decorate Python functions with `@tool` to expose your business logic
- **Build the agent**: Combine provider, tools, name, and system instructions via `provider.create_agent()`
- **Execute**: Use `agent.run()` for responses or `await agent.run(..., stream=True)` for streaming
- **Productionize**: Add timing, logging, and evaluator agents from Lesson 10

This architecture separates concerns cleanly—your custom logic lives in tools, the framework handles LLM orchestration, and the repository's lessons provide patterns for scaling to production.

## Frequently Asked Questions

### What Azure services do I need to run my custom agent?

You need an **Azure AI Foundry** project with a deployed language model (GPT-4o or equivalent). The `AzureAIProjectAgentProvider` connects to this endpoint using the `AZURE_AI_PROJECT_ENDPOINT` and `AZURE_AI_MODEL_DEPLOYMENT_NAME` variables. No additional Azure services are required for basic operation, though you may add Azure AI Search for RAG or Azure Cosmos DB for persistent state.

### Can I use my own LLM provider instead of Azure?

The `agent-framework` package used throughout ai-agents-for-beginners is optimized for Azure AI Foundry. While the underlying abstractions may support other providers in future releases, the current lesson code and `AzureAIProjectAgentProvider` specifically target Azure. For non-Azure LLMs, you would need to implement a custom provider class matching the framework's interface.

### How do I add authentication or rate limiting to my custom tools?

Tool-level concerns like authentication and rate limiting should be implemented inside your decorated functions before the business logic. The `@tool` decorator in `agent-framework` does not impose these constraints—you control them entirely. For production deployments, consider adding Azure API Management in front of your agent endpoints, or implement middleware patterns from Lesson 10's observability patterns to log and throttle tool invocations.

### Where should I store persistent conversation state?

The basic agent pattern in ai-agents-for-beginners operates statelessly—each `agent.run()` call is independent. For persistent state, you have two recommended approaches: (1) implement state management inside your custom tools using databases like Azure Cosmos DB or SQL Server, or (2) build a sequential workflow pattern from Lesson 14 where you explicitly pass state between agent steps. The production lesson (Lesson 10) also demonstrates logging patterns that can be extended to capture conversation history.