Сервер агента

Агент-сервер — это библиотека, которая превращает ваш код агента в сервис. Он инкапсулирует цикл работы агента в HTTP-сервер, определяет API, который клиенты вызывают для запуска агента, управляет клиентскими соединениями и определяет, что происходит при прерывании выполнения. Сервер агента работает в среде выполнения агента. Чтобы узнать, как эти слои сочетаются друг с другом, смотрите Развертывание агентов в Azure Databricks.

Для новых агентов Databricks рекомендует сервер агентов, который предоставляет AgentKit , и который описан на этой странице. Для сравнения с устаревшими серверами агентов см. раздел «Сравните серверы агентов на Azure Databricks».

Requirements

Python 3.10 и выше.
Пакет databricks-agentbricks, который включает AgentKit. Проекты, которые вы создаёте с помощью agentbricks init, объявляют его как зависимость.

AgentKit

AgentKit — это библиотека Agent Bricks для создания агентов, работающих на Agent Runtime. Он предоставляет сервер агента, обслуживающий вашего агента, а также клиенты и помощники для памяти агента, сессий агента, трассировки и аутентификации. Проекты, которые вы создаёте с помощью CLI Agent Bricks , по умолчанию используют AgentKit.

Сервер агента

AgentKit предоставляет свой агентный сервер через класс DurableAgentServer. Агент-сервер обертывает ваш агентный цикл в HTTP-сервер, который обслуживает API вызова, отслеживает каждый запуск и восстанавливает запуски, которые были прерваны сбоем или перезагрузкой. Он предоставляет:

Один API для каждого режима запроса: синхронные, потоковые и фоновые вызовы, плюс повторное соединение потоков — всё это обслуживается одним и тем же обработчиком.
Идемпотентные вызовы: ID вызова, генерируемый клиентом, гарантирует, что повторный запрос не запустит повторный экземпляр выполнения.
Упорядоченные сессии: Вызовы в одной сессии проходят по очереди, по порядку.
Постоянное состояние запуска: при развертывании состояние запуска, события и результаты сохраняются при перезапусках работника.
Восстановление после сбоя: сервер обнаруживает прерванные запуски и запускает повторную попытку.
Авторизация пользователя, отправившего запрос: Инструменты могут действовать с разрешениями пользователя, отправившего запрос.
Пользовательские конечные точки: Сервер агентов — это приложение FastAPI, так что вы можете добавлять собственные роуты.

Что включает в себя AgentKit

AgentKit — это databricks_agentkit библиотека Python. Она экспортирует следующее:

Экспорт	Description
`DurableAgentServer`, `InvocationContext`	Сервер агента и контекст, который он передаёт вашим обработчикам вызова и восстановления.
`AgentKitClient`	Клиент для памяти агента и хранилищ сессий агента. Он создаёт и получает хранилища, а также предоставляет память и сеансы хранилищ в виде объектов `Memory`, `MemoryStore`, `MemorySearchResult`, `Session`, `SessionStore` и `SessionItem`.
`configure_tracing`, `start_trace`	Настройте трассировку MLflow для агента и начните трассировку для отдельной операции.
`workspace_client`, `workspace_headers`	Создайте аутентифицированный SDK `WorkspaceClient`Databricks или получите заголовки аутентификации для прямых HTTP-вызовов из среды агента.
`list_ai_gateway_model_services`	Перечислите сервисы моделей, которые агент может вызывать через Unity Gateway.

Библиотека также включает помощники фреймворков в databricks_agentkit.langgraph и databricks_agentkit.openai, которые используют созданные шаблоны для подключения каждого фреймворка к хранилищу сессий. Сведения об API памяти и сессий см. в Память агента и Сессии агента.

Зарегистрируйте агент

Когда вы создаёте проект с agentbricks init, CLI делает это за вас. Сгенерированный runtime/main.py создаёт сервер и регистрирует обработчики вызова и восстановления шаблона, поэтому вы редактируете код агента только в agent/. Следуйте шагам в этом разделе, чтобы подключить существующего агента или написать собственный обработчик.

Создайте DurableAgentServer и зарегистрируйте асинхронный обработчик вызова с @app.invoke. Обработчик получает input запроса и контекст вызова и возвращает результат, сериализуемый в JSON. Публикуйте прогресс как события с context.emit.

from databricks_agentkit import DurableAgentServer, InvocationContext

app = DurableAgentServer()


@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    await context.emit({"type": "status", "message": "Looking that up"})
    answer = await run_my_agent(input, session_id=context.session_id)
    return {"answer": answer}

Можно зарегистрировать один обработчик вызова, и сервер не запускается без него. Обработчик обслуживает все режимы запроса: клиент выбирает, ждать результата, транслировать события или запустить в фоновом режиме.

Чтобы запустить сервер локально, запустите его с помощью agentbricks dev. Проекты, которые вы создаёте с помощью agentbricks init, включают входную точку, которая запускает сервер через Uvicorn, и файл app.yaml, который запускает ту же точку входа после развертывания.

Контекст вызова

Второй аргумент обработчика — это InvocationContext:

Атрибут	Description
`invocation_id`	ID, который клиент отправил для этого вызова.
`session_id`	Сессия, к которой принадлежит вызов, или `None`, если клиент не отправил идентификатор сессии.
`attempt`	Номер попытки. Первая попытка — `1`.
`is_recovery`	`True` когда обработчик восстановления запускает попытку замены.
`emit(event)`	Хранит JSON-событие, доставляет его стриминговым клиентам и возвращает его позицию в потоке.
`request_auth`	Резолвер учетных данных запроса-пользователя, когда агенту требуется авторизация пользователя запроса. В противном случае — `None`.

API вызова

DurableAgentServer обслуживает API вызова по адресу /api/invocations:

POST /api/invocations начинает вызов. По умолчанию запрос ждёт результата. Настройте stream, чтобы получать события как Server-Sent Events, или background, чтобы сразу возвращать ответ с URL статуса.
GET /api/invocations/<id> возвращает статус вызова, а после завершения — его выходные данные.
GET /api/invocations/<id>/events?after=<event-id> потоково передает сохраненные события, чтобы клиент мог переподключиться после разрыва соединения.

Для полей запросов, примеров и форматов ответов см. Запрос агентов, развернутых в Azure Databricks.

Идемпотентность

Клиенты присылают UUID id при каждом вызове. Сервер рассматривает идентификатор как ключ идемпотентности, пока сервер хранит запись вызова: повторная отправка того же запроса возвращает существующий вызов вместо повторного запуска агента. Повторное использование идентификатора для другого запроса возвращает ошибку 409.

Sessions

Клиенты могут отправлять session_id, чтобы сгруппировать вызовы в одну беседу. Сервер хранит ID сессии отдельно от input, передаёт его вашему обработчику как context.session_id и запускает вызовы с одним и тем же ID сессии по очереди, по порядку. Сервер не определяет сеанс по идентификатору вызова или входным данным. Без идентификатора сессии инвокация является бессессионной.

Состояние выполнения

DurableAgentServer хранит запросы, статус, сигналы активности каждого вызова, события и результат в Хранилище Runtime.

Локальная разработка: agentbricks dev использует внутрипроцессный Runtime Store. API вызова ведёт себя аналогично, но состояние запуска теряется при остановке процесса, и сервер не перезапускает прерванную работу.
Развернутые агенты: для Runtime Store каждого развертывания в проекте Lakebase под управлением Azure Databricks предоставляется выделенная база данных, которая повторно используется при повторном развертывании. Вы не можете использовать собственный проект Lakebase для Runtime Store, и вам не нужно создавать или привязывать его самостоятельно. Результаты и события сохраняются при перезапуске работника, и любой экземпляр агента может обрабатывать запросы о состоянии и повторном подключении. agentbricks deployments delete удаляет Runtime Store при развертывании.

Runtime Store хранит состояние исполнения сервера. Это отдельное хранилище, отличное от хранилищ сеансов и памяти, которые ваш агент использует для истории разговоров и долгосрочной памяти.

Восстановление после аварии

Чтобы восстановить запуски, которые прерываются из-за сбоя или перезапуска воркера, зарегистрируйте обработчик восстановления с @app.recover. Когда развернутый сервер обнаруживает, что heartbeat-сигналы выполнения прекратились, он начинает попытку замены на доступном воркере и вызывает обработчик восстановления с исходными входными данными.

@app.recover
async def recover(input, context: InvocationContext) -> dict:
    # Resume from the agent's last checkpoint in the session store,
    # or replay the input if that's safe for your agent.
    return await resume_my_agent(input, session_id=context.session_id)

Если вы не регистрируете обработчик восстановления, автоматическое восстановление отключается, и сервер записывает предупреждение в журнал при запуске.

Восстановление происходит следующим образом:

Когда начинается восстановление: Каждая выполняемая попытка отправляет сигнал heartbeat каждые несколько секунд. Если heartbeat-сигналы прекращаются, например, из-за сбоя воркера, перезапуска или замены во время повторного развертывания, сервер обнаруживает устаревший запуск за считанные секунды и начинает попытку замены.
Когда повторная обработка не начинается: если ваш обработчик вызывает исключение, вызов не срабатывает, и сервер не повторяет его. Восстановление покрывает прерванных воркеров, а не ошибки в коде агента.
Количество попыток: сервер не ограничивает количество попыток восстановления. Каждая попытка замены увеличивает context.attempt на один. Чтобы остановиться после нескольких попыток, в обработчике восстановления проверьте context.attempt и выдайте ошибку.
Ручное восстановление: Вы не можете запустить восстановление вручную. Повторная отправка запроса с тем же идентификатором вызова возвращает существующий вызов вместо начала новой попытки.

Recovery может запускать ваш код агента более одного раза для одного и того же вызова. Прерванная попытка могла уже обратиться к внешним системам до начала повторной попытки, так что сделайте эти вызовы идемпотентными.

Авторизация пользователя по запросу

По умолчанию инструменты вашего агента работают с правами субъекта-службы приложения. Чтобы запустить инструмент с правами пользователя, отправившего запрос, объявите авторизацию пользователя в agent.toml:

Для управляемого инструмента установите auth = "user" для записи инструмента. agentbricks tools add Команды для MCP-серверов, песочниц и агентов Genie, пишут auth = "user" по умолчанию. Передайте --auth app, чтобы использовать идентификатор приложения.
Для инструмента, который вы пишете в коде, объявляйте требование и любые области API, которые Agent Bricks не может определить:
```
[auth.user]
required = true
additional_api_scopes = ["sql"]
```

Когда агенту требуется авторизация пользователя, DurableAgentServer он считывает учетные данные пользователя из доверенных заголовков запросов приложений Databricks и хранит их в памяти только для активной попытки. Runtime Store не хранит учетные данные учетной записи. В вашем обработчике получите для пользователя клиент рабочего пространства из context.request_auth:

@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    user_client = context.request_auth.client_for("user")
    me = user_client.current_user.me()
    return {"answer": f"Hello, {me.user_name}"}

client_for("app") Возвращает клиент, использующий субъект-службу приложения. resolver закрывается, когда попытка заканчивается, поэтому вызывайте его внутри обработчика, а не храните объект клиента. Когда вы запускаете агента локально с agentbricks dev, client_for("user") использует ваши локальные учетные данные.

При развертывании agentbricks deploy запрашивает пользовательские области Databricks Apps, которые нужны вашим инструментам. Чтобы добавить недостающие области в существующее приложение, передайте --allow-user-scope-update. См. раздел "Настройка авторизации" в приложении Databricks.

Вызовы request-user используют одинаковые синхронные, потоковые, фоновые и API повторного подключения. Поскольку сервер не хранит учетные данные пользователя, он не может восстановить прерванный вызов пользователя по запросу. Попытка замены проваливается из-за ошибки MCP_USER_AUTH_RECOVERY_UNSUPPORTED до того, как ваши обработчики выполняются.

Добавить пользовательские конечные точки

DurableAgentServer это приложение FastAPI. Добавляйте маршруты наряду с API invocation так же, как вы добавляете их в любое приложение FastAPI:

@app.get("/status")
async def status() -> dict:
    return {"ready": True}

Шаблоны платформ

agentbricks init генерирует два каталога:

agent/ содержит ваш фреймворк-код: модель, запросы и инструменты.
runtime/ содержит адаптер, который соединяет фреймворк с DurableAgentServer, и входную точку, регистрирующую обработчики вызова и восстановления адаптера.

Адаптер преобразует каждое вызов в вызов агентного цикла фреймворка, а выходные данные фреймворка — в события и результат. Оба шаблона регистрируют обработчик восстановления. Шаблон LangGraph возобновляется с последней контрольной точки в хранилище сессий, а шаблон SDK OpenAI Agents повторно выполняет запрос в той же сессии. Чтобы подключить существующий агент, добавьте адаптер и точку входа DurableAgentServer, и задайте server = "agentbricks" в разделе [agent] файла agent.toml.

Сравнение серверов агента в Azure Databricks

Azure Databricks предоставляет три сервера агентов: сервер агентов AgentKit и два устаревших сервера агентов, которые используют более ранние шаблоны приложений.

сервер агента	Пакет	Клиентский API	Устойчивое выполнение	Используется кем
AgentKit (`DurableAgentServer`, рекомендовано)	`databricks_agentkit`, в `databricks-agentbricks` упаковке	API вызова в `/api/invocations`: синхронные, потоковые и фоновые запуски с повторным подключением потока	Хранилище среды выполнения, подготавливаемое `agentbricks deploy`, плюс восстановление после сбоев через обработчик восстановления	Проекты, которые вы создаёте с помощью CLI Agent Bricks
`LongRunningAgentServer` (устаревшая версия)	`databricks_ai_bridge.long_running`, в `databricks-ai-bridge[agent-server]` упаковке	API OpenAI Responses в `/responses`, с фоновыми запусками и возобновлением стриминга	Состояние выполнения в базе данных Lakebase, которую вы настраиваете. После сбоя новая попытка продолжает выполнение на основе журнала событий прерванной попытки.	`agent-openai-advanced` и `agent-langgraph-advanced`
MLflow `AgentServer` (устаревший)	`mlflow.genai.agent_server`, в `mlflow` упаковке	API OpenAI Responses на `/responses`: синхронные и потоковые запуски	None	Шаблоны базовых приложений, такие как `agent-openai-agents-sdk`

LongRunningAgentServer расширяет MLflow AgentServer, и оба служат агентам, реализующим интерфейс MLflow ResponsesAgent. Чтобы развернуть и поддерживать агент, использующий один из них, см. «Запуск агентов в приложениях Databricks с использованием устаревшего агентного сервера». Чтобы запросить агента на любом из этих серверов, см. раздел «Запрос агентов, развернутых в Azure Databricks».

Limitations

Вы не можете изменить сервер агента существующего развертывания. Чтобы переключиться между DurableAgentServer и своим сервером, создайте новый проект с agentbricks init --server нужной опцией и разверните его под новым именем.
Изменение server поля в agent.toml не преобразует существующий код сервера в DurableAgentServer.
Авторизация пользователя по запросу требует server = "agentbricks".

Дополнительные ресурсы

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-10-13