Skip to main content
subagent CX Codex

custom-agents — Claude Code subagent: build your own agents

Subagent for building custom agents with Microsoft Agent Framework. Inherit from AIAgent and implement methods to handle session management and message processing.

MIT ★ 521 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/custom-agents.md
Open on GitHub

What custom-agents does

custom-agents shows how to create an agent by extending the AIAgent class and implementing session and message-handling methods. The framework provides base classes like InMemoryAgentSession and ServiceIdAgentSession to manage conversation state and chat history.

Your agent must implement two factory methods: CreateSessionCoreAsync to create a new session and DeserializeSessionCoreAsync to restore from saved state. This pattern gives your agent control over session lifecycle and lets you attach custom behavior.

For the core logic, implement RunCoreAsync for standard responses and RunCoreStreamingAsync for streamed replies. Both should fetch messages from the session's ChatHistoryProvider to maintain multi-turn conversation context. You need the Microsoft.Agents.AI.Abstractions NuGet package.

What it helps with

  • build a custom agent with message transformation logic
  • manage session state and conversation history
  • implement both synchronous and streaming response methods
  • serialize and deserialize session state to JSON

Example prompts for the agent

  • Create an agent that echoes messages back in uppercase
  • Set up a session that stores chat history in memory
  • Implement the session factory methods to control agent lifecycle

How to install custom-agents

Manually: put the files in place

.claude/agents/custom-agents.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about custom-agents

How do I install custom-agents in Claude Code?

Add the configuration file .claude/agents/custom-agents.md to your project root. Then add the NuGet package with dotnet add package Microsoft.Agents.AI.Abstractions --prerelease.

What does custom-agents do?

It provides a working example of building an agent with Microsoft Agent Framework. Demonstrates how to inherit from AIAgent, manage session state, and process incoming messages in both synchronous and streaming modes.

What session base classes are available?

InMemoryAgentSession stores chat history in memory and serializes to JSON. ServiceIdAgentSession does not persist history but lets you associate an external ID with the session for separate storage.

Source text

custom-agents.md · MIT
---
title: Custom Agents
description: Learn how to build custom agents with Microsoft Agent Framework.
zone_pivot_groups: programming-languages
author: westey-m
ms.topic: tutorial
ms.author: westey
ms.date: 06/01/2026
ms.service: agent-framework
---

# Custom Agents

::: zone pivot="programming-language-csharp"

Microsoft Agent Framework supports building custom agents by inheriting from the `AIAgent` class and implementing the required methods.

This article shows how to build a simple custom agent that parrots back user input in upper case.
In most cases building your own agent will involve more complex logic and integration with an AI service.

## Getting Started

Add the required NuGet packages to your project.

```dotnetcli
dotnet add package Microsoft.Agents.AI.Abstractions --prerelease
```

## Create a Custom Agent

### The Agent Session

To create a custom agent you also need a session, which is used to keep track of the state
of a single conversation, including message history, and any other state the agent needs to maintain.

To make it easy to get started, you can inherit from various base classes that implement common session storage mechanisms.

1. `InMemoryAgentSession` - stores the chat history in memory and can be serialized to JSON.
1. `ServiceIdAgentSession` - doesn't store any chat history, but allows you to associate an ID with the session, under which the chat history can be stored externally.

For this example, you'll use the `InMemoryAgentSession` as the base class for the custom session.

```csharp
internal sealed class CustomAgentSession : InMemoryAgentSession
{
    internal CustomAgentSession() : base() { }
    internal CustomAgentSession(JsonElement serializedSessionState, JsonSerializerOptions? jsonSerializerOptions = null)
        : base(serializedSessionState, jsonSerializerOptions) { }
}
```

### The Agent class

Next, create the agent class itself by inheriting from the `AIAgent` class.

```csharp
internal sealed class UpperCaseParrotAgent : AIAgent
{
}
```

### Constructing sessions

Sessions are always created via two factory methods on the agent class.
This allows for the agent to control how sessions are created and deserialized.
Agents can therefore attach any additional state or behaviors needed to the session when constructed.

Two methods are required to be implemented:

```csharp
    protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
        => new(new CustomAgentSession());

    protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
        => new(new CustomAgentSession(serializedState, jsonSerializerOptions));
```

### Core agent logic

The core logic of the agent is to take any input messages, convert their text to upper case, and return them as response messages.

Add the following method to contain this logic.
The input messages are cloned, since various aspects of the input messages have to be modified to be valid response messages. For example, the role has to be changed to `Assistant`.

```csharp
    private static IEnumerable<ChatMessage> CloneAndToUpperCase(IEnumerable<ChatMessage> messages, string agentName) => messages.Select(x =>
        {
            var messageClone = x.Clone();
            messageClone.Role = ChatRole.Assistant;
            messageClone.MessageId = Guid.NewGuid().ToString();
            messageClone.AuthorName = agentName;
            messageClone.Contents = x.Contents.Select(c => c is TextContent tc ? new TextContent(tc.Text.ToUpperInvariant())
            {
                AdditionalProperties = tc.AdditionalProperties,
                Annotations = tc.Annotations,
                RawRepresentation = tc.RawRepresentation
            } : c).ToList();
            return messageClone;
        });
```

### Agent run methods

Finally, you need to implement the two core methods that are used to run the agent:
one for non-streaming and one for streaming.

For both methods, you need to ensure that a session is provided, and if not, create a new session.
Messages can be retrieved and passed to the `ChatHistoryProvider` on the session.
If you don't do this, the user won't be able to have a multi-turn conversation with the agent and each run will be a fresh interaction.

```csharp
    protected override async Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
    {
        session ??= await this.CreateSessionAsync(cancellationToken);

        // Get existing messages from the store
        var invokingContext = new ChatHistoryProvider.InvokingContext(messages);
        var storeMessages = await typedSession.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);

        List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.DisplayName).ToList();

        // Notify the session of the input and output messages.
        var invokedContext = new ChatHistoryProvider.InvokedContext(messages, storeMessages)
        {
            ResponseMessages = responseMessages
        };
        await typedSession.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);

        return new AgentResponse
        {
            AgentId = this.Id,
            ResponseId = Guid.NewGuid().ToString(),
            Messages = responseMessages
        };
    }

    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        session ??= await this.CreateSessionAsync(cancellationToken);

        // Get existing messages from the store
        var invokingContext = new ChatHistoryProvider.InvokingContext(messages);
        var storeMessages = await typedSession.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);

        List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.DisplayName).ToList();

        // Notify the session of the input and output messages.
        var invokedContext = new ChatHistoryProvider.InvokedContext(messages, storeMessages)
        {
            ResponseMessages = responseMessages
        };
        await typedSession.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);

        foreach (var message in responseMessages)
        {
            yield return new AgentResponseUpdate
            {
                AgentId = this.Id,
                AuthorName = this.DisplayName,
                Role = ChatRole.Assistant,
                Contents = message.Contents,
                ResponseId = Guid.NewGuid().ToString(),
                MessageId = Guid.NewGuid().ToString()
            };
        }
    }
```

> [!TIP]
> See the [.NET samples](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples) for complete runnable examples.

## Tools

A custom `AIAgent` has whatever tool surface you decide to give it. If you wrap an existing `IChatClient` and pass `tools` through, you inherit that client's tool support — see, for example, the [OpenAI](../../integrations/by-component/model-providers/openai.md#tools), [Azure OpenAI](../../integrations/by-component/model-providers/azure-openai.md#tools), or [Microsoft Foundry](../../integrations/by-component/model-providers/microsoft-foundry.md#tools) provider pages for what the underlying clients support. If your custom agent does not call a chat client (for example, the echo agent above), there are no tools to invoke.

## Using the Agent

If the `AIAgent` methods are all implemented correctly, the agent would be a standard `AIAgent` and support standard agent operations.

For more information on how to run and interact with agents, see the [Agent getting started tutorials](../../get-started/your-first-agent.md).

::: zone-end
::: zone pivot="programming-language-python"

Microsoft Agent Framework supports building custom agents by inheriting from the `BaseAgent` class and implementing the required methods.

This document shows how to build a simple custom agent that echoes back user input with a prefix.
In most cases building your own agent will involve more complex logic and integration with an AI service.

## Getting Started

Add the required Python packages to your project.

```bash
pip install agent-framework-core
```

## Create a Custom Agent

### The Agent Protocol

The framework provides the `SupportsAgentRun` protocol that defines the interface all agents must implement. Custom agents can either implement this protocol directly or extend the `BaseAgent` class for convenience.

```python
from typing import Any, Literal, overload
from collections.abc import Awaitable, Sequence
from agent_framework import (
    AgentResponse,
    AgentResponseUpdate,
    AgentSession,
    Message,
    ResponseStream,
    SupportsAgentRun,
)

class MyCustomAgent(SupportsAgentRun):
    """A custom agent that implements the SupportsAgentRun directly."""

    @property
    def id(self) -> str:
        """Returns the ID of the agent."""
        ...

    @overload
    def run(
        self,
        messages: str | Message | Sequence[str | Message] | None = None,
        *,
        stream: Literal[False] = False,
        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> Awaitable[AgentResponse]: ...

    @overload
    def run(
        self,
        messages: str | Message | Sequence[str | Message] | None = None,
        *,
        stream: Literal[True],
        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> ResponseStream[AgentResponseUpdate, AgentResponse]: ...

    def run(
        self,
        messages: str | Message | Sequence[str | Message] | None = None,
        *,
        stream: bool = False,
        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> Awaitable[AgentResponse] | ResponseStream[AgentResponseUpdate, AgentResponse]:
        """Execute the agent and return either an awaitable response or a ResponseStream."""
        ...
```

> [!TIP]
> Add `@overload` signatures to `run()` so IDEs and static type checkers infer the return type based on `stream` (`Awaitable[AgentResponse]` for `stream=False` and `ResponseStream[AgentResponseUpdate, AgentResponse]` for `stream=True`).

### Using BaseAgent

The recommended approach is to extend the `BaseAgent` class, which provides common functionality and simplifies implementation:

```python
import asyncio
from collections.abc import AsyncIterable, Awaitable, Sequence
from typing import Any, Literal, overload

from agent_framework import (
    AgentResponse,
    AgentResponseUpdate,
    AgentSession,
    BaseAgent,
    Content,
    Message,
    ResponseStream,
    normalize_messages,
)


class EchoAgent(BaseAgent):
    """A simple custom agent that echoes user messages with a prefix."""

    echo_prefix: str = "Echo: "

    def __init__(
        self,
        *,
        name: str | None = None,
        description: str | None = None,
        echo_prefix: str = "Echo: ",
        **kwargs: Any,
    ) -> None:
        super().__init__(
            name=name,
            description=description,
            echo_prefix=echo_prefix,
            **kwargs,
        )

    @overload
    def run(
        self,
        messages: str | Message | Sequence[str | Message] | None = None,
        *,
        stream: Literal[False] = False,
        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> Awaitable[AgentResponse]: ...

    @overload
    def run(
        self,
        messages: str | Message | Sequence[str | Message] | None = None,
        *,
        stream: Literal[True],
        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> ResponseStream[AgentResponseUpdate, AgentResponse]: ...

    def run(
        self,
        messages: str | Message | Sequence[str | Message] | None = None,
        *,
        stream: bool = False,
        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> Awaitable[AgentResponse] | ResponseStream[AgentResponseUpdate, AgentResponse]:
        """Execute the agent.

        Args:
            messages: The message(s) to process.
            stream: If True, return a ResponseStream of updates.
            session: The conversation session (optional).

        Returns:
            When stream=False: An awaitable AgentResponse.
            When stream=True: A ResponseStream with AgentResponseUpdate items and final response support.
        """
        if stream:
            return ResponseStream(
                self._run_stream(messages=messages, session=session, **kwargs),
                finalizer=AgentResponse.from_updates,
            )
        return self._run(messages=messages, session=session, **kwargs)

    async def _run(
        self,
        messages: str | Message | Sequence[str | Message] | None = None,
        *,
        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> AgentResponse:
        normalized_messages = normalize_messages(messages)

        if not normalized_messages:
            response_message = Message(
                role="assistant",
                contents=[Content.from_text("Hello! I'm a custom echo agent. Send me a message and I'll echo it back.")],
            )
        else:
            last_message = normalized_messages[-1]
            echo_text = f"{self.echo_prefix}{last_message.text}" if last_message.text else f"{self.echo_prefix}[Non-text message received]"
            response_message = Message(role="assistant", contents=[Content.from_text(echo_text)])

        if session is not None:
            stored = session.state.setdefault("memory", {}).setdefault("messages", [])
            stored.extend(normalized_messages)
            stored.append(response_message)

        return AgentResponse(messages=[response_message])

    async def _run_stream(
        self,
        messages: str | Message | Sequence[str | Message] | None = None,
        *,
        session: AgentSession | None = None,
        **kwargs: Any,
    ) -> AsyncIterable[AgentResponseUpdate]:
        normalized_messages = normalize_messages(messages)

        if not normalized_messages:
            response_text = "Hello! I'm a custom echo agent. Send me a message and I'll echo it back."
        else:
            last_message = normalized_messages[-1]
            response_text = f"{self.echo_prefix}{last_message.text}" if last_message.text else f"{self.echo_prefix}[Non-text message received]"

        words = response_text.split()
        for i, word in enumerate(words):
            chunk_text = f" {word}" if i > 0 else word
            yield AgentResponseUpdate(
                contents=[Content.from_text(chunk_text)],
                role="assistant",
            )
            await asyncio.sleep(0.1)

        if session is not None:
            complete_response = Message(role="assistant", contents=[Content.from_text(response_text)])
            stored = session.state.setdefault("memory", {}).setdefault("messages", [])
            stored.extend(normalized_messages)
            stored.append(complete_response)
```

## Tools

A custom `BaseAgent` has whatever tool surface you decide to give it. If you wrap an existing chat client and pass `tools` through, you inherit that client's tool support — see, for example, the [OpenAI](../../integrations/by-component/model-providers/openai.md#tools), [Microsoft Foundry](../../integrations/by-component/model-providers/microsoft-foundry.md#tools), or [Anthropic](../../integrations/by-component/model-providers/anthropic.md#tools) provider pages for what the underlying clients support. If your custom agent does not call a chat client (for example, the echo agent above), there are no tools to invoke.

## Using the Agent

If agent methods are all implemented correctly, the agent supports standard operations, including streaming via `ResponseStream`:

```python
stream = echo_agent.run("Stream this response", stream=True, session=echo_agent.create_session())
async for update in stream:
    print(update.text or "", end="", flush=True)
final_response = await stream.get_final_response()
```

For more information on how to run and interact with agents, see the [Agent getting started tutorials](../../get-started/your-first-agent.md).

::: zone-end

::: zone pivot="programming-language-go"
## Custom providers

You can create a custom provider by implementing `agent.ProviderConfig` and passing it to `agent.New`:

```go
import (
    "context"
    "iter"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/message"
)

a := agent.New(agent.ProviderConfig{
    ProviderName: "my-custom-provider",
    Run: func(ctx context.Context, messages []*message.Message,
        options ...agent.Option) iter.Seq2[*agent.ResponseUpdate, error] {
        // Your custom LLM logic here
        return func(yield func(*agent.ResponseUpdate, error) bool) {
            yield(&agent.ResponseUpdate{
                Role: message.RoleAssistant,
                Contents: []message.Content{
                    &message.TextContent{Text: "Hello from custom provider!"},
                },
            }, nil)
        }
    },
}, agent.Config{
    Name: "CustomAgent",
})
```

### ProviderConfig fields

| Field | Purpose |
|---|---|
| `CreateSession` | Create a new session for the provider |
| `Run` | Execute a request and stream response updates |
| `Middlewares` | Add provider-scoped middleware that runs after history and context providers |
| `Format` | Generate a response format descriptor for structured output |
| `Unmarshal` | Decode structured output into a target type |

::: zone-end
## Next steps

> [!div class="nextstepaction"]
> [Running Agents](running-agents.md)

© westey-m · MIT · managedcode/dotnet-skills

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set38

The whole set →
microsoft-agent-framework microsoft-agent-framework is a Claude Code skill for building and reviewing .NET apps with Microsoft Agent Framework. It guides choices around agent types, sessions, tools, workflows, and hosting. CX Codex +1 ★ 521repo stars function-tools function-tools — a subagent that lets your agent call your code functions as tools. Use it when you want the AI assistant to autonomously decide when to invoke a specific function—like fetching weather data or querying an API. CX Codex ★ 521repo stars runtime-context Guides runtime context configuration across middleware, session state, and tool invocations for C# AI agents. CX Codex ★ 521repo stars running-agents The running-agents subagent explains how to run Agent Framework agents with one final result or streamed updates. Use it when wiring agent execution into a project. CX Codex ★ 521repo stars structured-outputs structured-outputs guides typed agent output setup in .NET using Azure AI. Helpful when building strict data contracts with C# models or raw JSON Schema definitions. CX Codex ★ 521repo stars termination termination is a Claude Code subagent that uses middleware to stop agents, block disallowed requests, and limit response length. It adds checks before and after an agent run. CX Codex ★ 521repo stars local-mcp-tools local-mcp-tools — a subagent for integrating Model Context Protocol servers into AI agents. Enables agents to access external tools and services through the MCP standard. CX Codex ★ 521repo stars index index is a Claude Code subagent documenting Agent Framework tool types and their support matrix across C#, Python, and Go. CX Codex ★ 521repo stars

Project sponsors

Companies that keep this analytics open