Обвязка агента

Ремня агента, иногда называемая ремнями ИИ, — это шаблон среды выполнения, который превращает языковую модель в агент, который может выполнять работу. Он управляет вызовами к модели и инструментам, отслеживает состояние и контекст беседы, применяет политики одобрения и может обеспечивать продвижение агента при выполнении многоэтапной задачи.

Agent Framework предоставляет готовую, продуманную платформу со всем необходимым для исследований, написания кода, анализа данных и других длительных задач. Вы предоставляете клиент чата и настраиваете только необходимые возможности приложения.

Architecture

Harness компонует существующие базовые компоненты Agent Framework, а не определяет отдельную среду выполнения для агентов:

  1. Клиент чата — подключает агент к модели.
  2. Конвейер обработки чата — добавляет вызов функций, добавление сообщений, сохранение истории для каждого вызова службы и необязательную компактизацию.
  3. Поставщики агентов и контекста — добавление инструкций в рамках сеанса, инструментов, памяти, состояния списка задач, режимов работы и необязательных возможностей.
  4. Промежуточный слой и декораторы — добавьте обработку согласований, наблюдаемость и необязательные циклы с ограничением числа итераций.
  5. UX приложения — передаёт ответы в потоковом режиме, отображает ход выполнения и собирает вводимые данные, такие как подтверждения на использование инструментов.

Полученный объект остается обычным агентом Agent Framework: HarnessAgent, который наследуется от AIAgent в .NET, или Agent, возвращаемым create_harness_agent в Python. Его сеансы используют те же абстракции session и context provider, что и другие агенты.

Матрица возможностей Harness

Capability Управление поведением Каноническое руководство
Вызов функции Включен с настраиваемым ограничением итерации для каждого запроса. Функциональные инструменты
Сохранение истории для каждого сервисного вызова Сохраняет историю после каждого вызова модели в ходе выполнения с вызовами инструментов. Сеансы
Сжатие Включается, если заданы ограничения на количество токенов или пользовательская стратегия. Уплотнения
Отслеживание todo Включено по умолчанию. Планирование и задачи
Режимы агента Режимы планирования и выполнения включены по умолчанию. Планирование и задачи
Доступ к памяти и файлам Память файла сеанса включена по умолчанию; Общий доступ к файлам включен. Поставщики контекстов
Утверждение инструмента По умолчанию включены постоянно действующие утверждения и правила автоматического утверждения. Утверждение инструмента
OpenTelemetry По умолчанию включена наблюдаемость агента. Наблюдаемость
Поиск в Интернете Добавлено по умолчанию, где выбранный клиент чата поддерживает его. Поиск в Интернете
Навыки агента Включен по умолчанию в .NET; согласие через поставщика или пути в Python. Навыки агента
Фоновые агенты Необязательное параллельное делегирование именованным дочерним агентам. Фоновые агенты
Выполнение команд в оболочке Собирается из пакета оболочки; Python-фабрика может автоматически подключить его. Средства оболочки
Циклическое повторение Необязательный повторный вызов с ограничением числа попыток, управляемый оценщиками или предикатами. Циклы агента

Делегирование фонового агента осуществляется отдельно от фоновых ответов, управляемых поставщиком. Фоновые агенты запускают дочерние агенты для выполнения делегированных задач; фоновые ответы опрашивают или возобновляют один запрос к поставщику с помощью токена продолжения.

Создайте агент Harness

Пакет Microsoft.Agents.AI.Harness предоставляет HarnessAgent в пространстве имен Microsoft.Agents.AI. Создайте один из любых IChatClient с помощью AsHarnessAgent или создайте HarnessAgent напрямую:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

AIAgent agent = chatClient.AsHarnessAgent();

AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);

Используйте HarnessAgentOptions, чтобы задать инструкции по эксплуатации на уровне среды выполнения, инструкции для конкретного агента и параметры функций:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    Name = "research-agent",
    HarnessInstructions = "Use tools deliberately and report verified results.",
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a research assistant focused on academic sources.",
    },
    MaxContextWindowTokens = 128_000,
    MaxOutputTokens = 16_384,
});

HarnessAgent.DefaultInstructions содержит указания по жгуту по умолчанию. HarnessInstructions отображается до ChatOptions.Instructions.

Настройка композиции

Возможности по умолчанию включают целевые параметры, включая DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry и DisableCompaction.

Добавьте пользовательские поставщики контекста с помощью AIContextProviders. Разрешите доступ к файлам с помощью FileAccessStore, фоновое делегирование с помощью BackgroundAgents и зацикливание с помощью LoopEvaluators.

Создайте агент Harness

Фабрика create_harness_agent возвращает полностью настроенный Agent:

from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient

agent = create_harness_agent(
    client=OpenAIChatClient(model="gpt-4o"),
)

session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)

Задайте отдельно инструкции на уровне harness и для конкретного агента:

agent = create_harness_agent(
    client=client,
    name="research-agent",
    harness_instructions="Use tools deliberately and report verified results.",
    agent_instructions="You are a research assistant focused on academic sources.",
    max_context_window_tokens=128_000,
    max_output_tokens=16_384,
)

DEFAULT_HARNESS_INSTRUCTIONS содержит указания по жгуту по умолчанию. harness_instructions отображается до agent_instructions.

Настройка композиции

Отключите параметры по умолчанию с помощью таких параметров, как disable_todo, disable_mode, disable_file_memory, disable_web_search, disable_tool_auto_approval и disable_compaction.

Замените встроенных поставщиков с помощью todo_provider или mode_provider, а поставщиков добавьте с помощью context_providers. Навыки подключаются только через skills_provider или skills_paths; доступ к файлам, фоновые агенты, инструменты оболочки и циклы также требуют явного включения.

Доступ к файлам использует предоставленное хранилище в качестве одной общей рабочей области по умолчанию. Чтобы изолировать файлы по идентификатору активного сеанса, включите доступ к файлам с областью действия сеанса:

from agent_framework import FileSystemAgentFileStore, create_harness_agent

file_store = FileSystemAgentFileStore("agent-files")
agent = create_harness_agent(
    client=client,
    file_access_store=file_store,
    file_access_session_scoped=True,
)

Для намеренного предоставления общего доступа в выбранных сеансах создайте FileAccessProvider(store=file_store, scope="tenant-1") напрямую и добавьте его через context_providers. Область действия — это непрозрачный ключ, который соответствует папке, управляемой поставщиком, а не пути. Ограниченный доступ переходит в закрытый режим вместо того, чтобы использовать корневой каталог общего хранилища, если нет ни активного идентификатора сеанса, ни явно заданной области.

Если доступ к файлам включён, используйте file_access_grep для поиска номеров строк, начиная с 1, file_access_read_lines для просмотра диапазона, включающего обе границы, и file_access_replace_lines для редактирования целых строк. file_access_read_lines добавляет в начало каждой строки её номер и символ табуляции; опускайте этот префикс при передаче текста строки в качестве expected_line. Ожидаемый текст предотвращает редактирование неправильной строки из-за устаревшего или несоответствующего номера строки.

file_access_grep использует регулярные выражения без учёта регистра, принимает шаблоны длиной до 256 символов и устанавливает ограничение в 10 секунд на весь поиск. Недопустимые или слишком длинные шаблоны, а также поисковые запросы, превышающие допустимый лимит, возвращают ошибку. Уточните каталог или шаблон перед повторной попыткой.

Это важно

file_access_grep возвращает текст совпавшей строки вместе с символом окончания строки. Пользовательская реализация AgentFileStore.search() должна возвращать номера строк, начинающиеся с 1, которые соответствуют тем же строкам, что и AgentFileStore.split_lines(), в тексте, возвращаемом read().

Замечание

create_harness_agent выпущен. Фоновые агенты, доступ к файлам и циклирование остаются экспериментальными и средства оболочки поступают из пакета предварительной версии agent-framework-tools .

Замечание

В настоящее время упакованный Go Harness недоступен. Создайте напрямую соответствующие пакеты агента на Go, поставщика контекста, компактизации и промежуточного ПО. Сведения о текущей поддержке см. в репозитории Agent Framework Go .

Пример пользовательского интерфейса терминала

Harness не предписывает интерфейс приложения. Репозиторий содержит примеры терминальных приложений, которые потоково выводят данные, отображают список дел и текущий режим, выводят запросы на подтверждение использования инструментов и предоставляют такие команды, как /todos, /mode и /exit.

Это важно

Эти консольные проекты являются примерами и не входят в состав фреймворка. Используйте их в качестве запускаемых примеров или в качестве отправной точки для собственного интерфейса терминала.

Пример точки входа .NET:HarnessConsole.RunAgentAsync

using Harness.Shared.Console;

await HarnessConsole.RunAgentAsync(
    agent,
    userPrompt: "Ask me anything to get started.");

Настройте пример с помощью наблюдателей, форматировщиков инструментов, обработчиков команд и HarnessConsoleOptions. См. примеры Harness для .NET.

В примере Python используется пакет console, основанный на Textual, наряду с примерами Harness:

from console import run_agent_async

await run_agent_async(agent)

Настройте пример с помощью наблюдателей, форматировщиков, команд и компонентов пользовательского интерфейса. См. примеры Python Harness.

В настоящее время в репозитории нет готового примера терминального приложения Go Harness.

Дальнейшие действия

Планируйте работу и отслеживайте задачи

Подробнее

  • Last updated on