AG-UIとは？AIエージェントとUIを繋ぐ新プロトコルの仕組みと実装方法を解説

mkdir ag-ui-reproduction
cd ag-ui-reproduction
python3 -m venv .venv

source .venv/bin/activate

.venv\Scripts\Activate.ps1

ag-ui-protocol==0.1.22
fastapi==0.141.1
uvicorn[standard]==0.52.4

python -m pip install -r requirements.txt

from ag_ui.core import RunAgentInput

import asyncio
from pathlib import Path
from ag_ui.core import (
    EventType,
    RunAgentInput,
    RunFinishedEvent,
    RunStartedEvent,
    StateDeltaEvent,
    StateSnapshotEvent,
    TextMessageContentEvent,
    TextMessageEndEvent,
    TextMessageStartEvent,
    ToolCallArgsEvent,
    ToolCallEndEvent,
    ToolCallResultEvent,
    ToolCallStartEvent,
)
from ag_ui.encoder import EventEncoder
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse, StreamingResponse
app = FastAPI(title="AG-UI minimal demo")
@app.get("/")
async def index():
    html = Path(__file__).with_name("index.html").read_text(encoding="utf-8")
    return HTMLResponse(html)
async def stream_message(encoder, message_id, chunks):
    yield encoder.encode(
        TextMessageStartEvent(
            type=EventType.TEXT_MESSAGE_START,
            message_id=message_id,
            role="assistant",
        )
    )
    for chunk in chunks:
        yield encoder.encode(
            TextMessageContentEvent(
                type=EventType.TEXT_MESSAGE_CONTENT,
                message_id=message_id,
                delta=chunk,
            )
        )
        await asyncio.sleep(0.18)
    yield encoder.encode(
        TextMessageEndEvent(
            type=EventType.TEXT_MESSAGE_END,
            message_id=message_id,
        )
    )
@app.post("/agent")
async def agent_endpoint(input_data: RunAgentInput, request: Request):
    encoder = EventEncoder(accept=request.headers.get("accept"))
    async def event_generator():
        yield encoder.encode(
            RunStartedEvent(
                type=EventType.RUN_STARTED,
                thread_id=input_data.thread_id,
                run_id=input_data.run_id,
            )
        )
        yield encoder.encode(
            StateSnapshotEvent(
                type=EventType.STATE_SNAPSHOT,
                snapshot={"phase": "受付", "調査済み件数": 0},
            )
        )
        async for event in stream_message(
            encoder,
            "msg_1",
            ["お問い合わせ", "内容を", "確認しています。", "社内規程を", "検索しますね。"],
        ):
            yield event
        yield encoder.encode(
            ToolCallStartEvent(
                type=EventType.TOOL_CALL_START,
                tool_call_id="tool_1",
                tool_call_name="search_knowledge_base",
                parent_message_id="msg_1",
            )
        )
        yield encoder.encode(
            ToolCallArgsEvent(
                type=EventType.TOOL_CALL_ARGS,
                tool_call_id="tool_1",
                delta='{"query": "有給休暇 繰り越し"}',
            )
        )
        yield encoder.encode(
            ToolCallEndEvent(
                type=EventType.TOOL_CALL_END,
                tool_call_id="tool_1",
            )
        )
        yield encoder.encode(
            ToolCallResultEvent(
                type=EventType.TOOL_CALL_RESULT,
                message_id="msg_tool_result",
                tool_call_id="tool_1",
                content="就業規則 第32条：未消化分は翌年度に限り繰り越せる（上限20日）",
            )
        )
        yield encoder.encode(
            StateDeltaEvent(
                type=EventType.STATE_DELTA,
                delta=[
                    {"op": "replace", "path": "/phase", "value": "回答生成"},
                    {"op": "replace", "path": "/調査済み件数", "value": 1},
                ],
            )
        )
        async for event in stream_message(
            encoder,
            "msg_2",
            ["就業規則", "第32条によると、", "未消化の有給休暇は", "翌年度に限り", "20日まで繰り越せます。"],
        ):
            yield event
        yield encoder.encode(
            RunFinishedEvent(
                type=EventType.RUN_FINISHED,
                thread_id=input_data.thread_id,
                run_id=input_data.run_id,
            )
        )
    return StreamingResponse(
        event_generator(), media_type=encoder.get_content_type()
    )

@app.post("/agent")
async def agent_endpoint(input_data: RunAgentInput, request: Request):
    encoder = EventEncoder(accept=request.headers.get("accept"))
    async def event_generator():
        yield encoder.encode(RunStartedEvent(
            type=EventType.RUN_STARTED,
            thread_id=input_data.thread_id,
            run_id=input_data.run_id,
        ))
        # この間にメッセージ、ツール、状態更新などのイベントを送る
        yield encoder.encode(RunFinishedEvent(
            type=EventType.RUN_FINISHED,
            thread_id=input_data.thread_id,
            run_id=input_data.run_id,
        ))
    return StreamingResponse(
        event_generator(),
        media_type=encoder.get_content_type(),
    )

<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <title>AG-UI 最小デモ</title>
  <style>
    :root{font-family:system-ui,sans-serif;color:#1c2333;background:#edf1f7}*{box-sizing:border-box}
    body{margin:0;padding:32px}.app{max-width:1100px;margin:auto;background:#fff;border-radius:16px;box-shadow:0 18px 50px #33415522;overflow:hidden}
    header{display:flex;align-items:center;padding:18px 22px;border-bottom:1px solid #e2e8f0}header h1{font-size:18px;margin:0}header span{margin-left:auto;color:#138a5b;font-size:13px}
    main{display:grid;grid-template-columns:1fr 1fr;min-height:580px}.panel{padding:22px}.panel+ .panel{border-left:1px solid #e2e8f0;background:#f8fafc}
    h2{font-size:14px;margin:0 0 18px;color:#64748b}.state{display:flex;gap:10px;margin-bottom:18px}.chip{padding:7px 10px;border-radius:8px;background:#eef2ff;color:#4547a9;font-size:12px}
    .messages{height:320px;overflow:auto}.message{padding:12px 14px;border-radius:12px;background:#eef2f7;margin-bottom:10px;line-height:1.55;font-size:14px;white-space:pre-wrap}.message.tool{background:#fff7df;border:1px solid #f3cf72}
    .event-log{height:460px;overflow:auto;font:12px/1.5 ui-monospace,monospace}.event{padding:8px 10px;margin-bottom:7px;border-left:3px solid #6366f1;background:#fff;white-space:pre-wrap;word-break:break-all}.event b{color:#494bb8}
    button{width:100%;padding:12px;border:0;border-radius:9px;background:#5558df;color:white;font-weight:700;cursor:pointer}button:disabled{opacity:.5;cursor:wait}
    .hint{text-align:center;color:#64748b;font-size:12px;margin-top:10px}@media(max-width:760px){body{padding:12px}main{grid-template-columns:1fr}.panel+.panel{border-left:0;border-top:1px solid #e2e8f0}}
  </style>
</head>
<body>
<div class="app">
  <header><h1>社内問い合わせエージェント</h1><span id="status">● 接続準備完了</span></header>
  <main>
    <section class="panel"><h2>ユーザーに見える画面</h2><div class="state"><div class="chip">phase: <b id="phase">未実行</b></div><div class="chip">調査済み: <b id="count">0</b>件</div></div><div class="messages" id="messages"><div class="message">質問：有給休暇は翌年度に繰り越せますか？</div></div><button id="run">エージェントを実行</button><div class="hint">クリックするとAG-UIイベントをSSEで受信します</div></section>
    <section class="panel"><h2>届いたAG-UIイベント</h2><div class="event-log" id="events"><div class="event">ここにイベントが順番に表示されます</div></div></section>
  </main>
</div>
<script>
const runButton=document.querySelector('#run');
const messages=document.querySelector('#messages');
const eventLog=document.querySelector('#events');
const statusLabel=document.querySelector('#status');
let currentMessage=null;
function showEvent(event){
  if(eventLog.textContent.includes('ここにイベント')) eventLog.innerHTML='';
  const row=document.createElement('div'); row.className='event';
  const title=document.createElement('b'); title.textContent=event.type;
  row.append(title,document.createElement('br'),document.createTextNode(JSON.stringify(event,null,2)));
  eventLog.append(row); eventLog.scrollTop=eventLog.scrollHeight;
}
function applyEvent(event){
  if(event.type==='RUN_STARTED') statusLabel.textContent='● 実行中';
  if(event.type==='STATE_SNAPSHOT'){document.querySelector('#phase').textContent=event.snapshot.phase;document.querySelector('#count').textContent=event.snapshot['調査済み件数']}
  if(event.type==='TEXT_MESSAGE_START'){currentMessage=document.createElement('div');currentMessage.className='message';messages.append(currentMessage)}
  if(event.type==='TEXT_MESSAGE_CONTENT'&¤tMessage) currentMessage.textContent+=event.delta;
  if(event.type==='TOOL_CALL_START'){const box=document.createElement('div');box.className='message tool';box.id='tool';box.textContent='ツール実行中：'+event.toolCallName;messages.append(box)}
  if(event.type==='TOOL_CALL_ARGS') document.querySelector('#tool').textContent+='\n引数：'+event.delta;
  if(event.type==='TOOL_CALL_RESULT') document.querySelector('#tool').textContent+='\n結果：'+event.content;
  if(event.type==='STATE_DELTA'){for(const op of event.delta){if(op.path==='/phase')document.querySelector('#phase').textContent=op.value;if(op.path==='/調査済み件数')document.querySelector('#count').textContent=op.value}}
  if(event.type==='RUN_FINISHED'){statusLabel.textContent='● 完了';runButton.disabled=false;runButton.textContent='もう一度実行'}
  messages.scrollTop=messages.scrollHeight;
}
runButton.addEventListener('click',async()=>{
  while(messages.children.length>1)messages.lastChild.remove();runButton.disabled=true;runButton.textContent='実行中…';eventLog.innerHTML='';
  const body={threadId:'thread-001',runId:crypto.randomUUID(),messages:[{id:'user-001',role:'user',content:'有給休暇は翌年度に繰り越せますか？'}],tools:[],context:[],state:{},forwardedProps:{}};
  try{
    const response=await fetch('/agent',{method:'POST',headers:{'Content-Type':'application/json','Accept':'text/event-stream'},body:JSON.stringify(body)});
    if(!response.ok) throw new Error('HTTP '+response.status+' '+await response.text());
    const reader=response.body.getReader(),decoder=new TextDecoder();let buffer='';
    while(true){const {value,done}=await reader.read();if(done)break;buffer+=decoder.decode(value,{stream:true});const blocks=buffer.split('\n\n');buffer=blocks.pop();for(const block of blocks){for(const line of block.split('\n')){if(line.startsWith('data: ')){const event=JSON.parse(line.slice(6));showEvent(event);applyEvent(event)}}}}
  }catch(error){statusLabel.textContent='● エラー';const row=document.createElement('div');row.className='event';row.textContent=error.message;eventLog.append(row);runButton.disabled=false;runButton.textContent='再実行'}
});
</script>
</body>
</html>

ag-ui-reproduction/
├── .venv/
├── index.html
├── requirements.txt
└── server.py

const response = await fetch('/agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify(body)
});

curl -N -X POST http://127.0.0.1:8000/agent \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  --data '{
    "threadId":"thread-001",
    "runId":"run-001",
    "messages":[{
      "id":"user-001",
      "role":"user",
      "content":"有給休暇は翌年度に繰り越せますか？"
    }],
    "tools":[],
    "context":[],
    "state":{},
    "forwardedProps":{}
  }'

curl.exe -N -X POST http://127.0.0.1:8000/agent `
  -H "Content-Type: application/json" `
  -H "Accept: text/event-stream" `
  --data '{
    "threadId":"thread-001",
    "runId":"run-001",
    "messages":[{
      "id":"user-001",
      "role":"user",
      "content":"有給休暇は翌年度に繰り越せますか？"
    }],
    "tools":[],
    "context":[],
    "state":{},
    "forwardedProps":{}
  }'

data: {"type":"RUN_STARTED","threadId":"thread-001","runId":"run-001"}
data: {"type":"STATE_SNAPSHOT","snapshot":{"phase":"受付","調査済み件数":0}}
data: {"type":"TEXT_MESSAGE_START","messageId":"msg_1","role":"assistant"}

data: {"type":"RUN_FINISHED","threadId":"thread-001","runId":"run-001"}