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

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:

# 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:

# 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 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.

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 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

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 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.

# 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 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

# 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

# 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

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:

# 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 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
05 - Agentic RAG	Integrate retrieval-augmented generation for knowledge bases	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

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}