Bug Report: session not found after successful session creation on /agent/run

[miclocher]

magec_bugreport.md

[achetronic]

Hello @miclocher I will review the file you send attached ASAP. At this moment, I have several agents running with several skills and MCPs connected and iaving no issues with that. Some friends are running similar setups too wo/ issues so I have to research a bit

I suspect it can be a race condition or an issue related to the MCP you are connecting that can cause the agent is not properly running.

You are completely right about the swagger not specifying the format of some fields and I will fix that for everyone, but just to unlock your research, at this moment it expect a UUID as app_name

Could you try again first with the uuid and without MCPs connected, and then connecting a different MCP, and then with your MCP? This would be super helpful for debugging this

[miclocher]

magec_bugreport_comment.md

[miclocher]

Hi achetronic :)

Thanks for your feedback. If you have time to take a look at the report, that would be great. We have described there how we set up Magec and what we tried to do to use your platform. It’s either a bug or a user error. I’d love to set up your system for our work and then use it in production.

What could help us right away is if you could share a working example of the exact sequence you use to:

Create a session
Call /agent/run

Including the exact app_name value you pass to /agent/run? This would help us identify whether we’re missing something in our setup.

Best regards

[seamusrex]

Hi @achetronic (and everyone on #26),

I'm Taiwanese (台灣人) — contributor from Taiwan. My first language is Traditional Chinese; I'm writing in English here for clarity—please excuse any awkward wording.

We put together a fix for the snake_case request body on POST /api/v1/agent/run and POST /api/v1/agent/run_sse: middleware normalizes app_name / user_id / session_id / new_message / state_delta to the camelCase fields ADK expects, which should stop the false "session not found" path described in this issue when the session was actually created.

Pull request: #27

Mirror / docs / patch file (reference): https://github.com/seamusrex/MagecAnalysis — 與上游 沒有共同 git 歷史，無法當成對 achetronic/magec 的 PR head；實際 PR 會從 Fork seamusrex/magec 送出（若維護者看到兩個倉庫名稱請以此說明為準）。

Verification pointers:

• cd server && go test ./middleware/ -run 'RunAgentJSONNormalize|Normalize' -count=1 -v
• Manual curl recipe (placeholders): docs/PR_VERIFICATION_GITHUB_26_CURL.md in that repo.

Happy to trim the PR to a minimal patch set if you want only #26-related files merged.

Thanks for maintaining Magec.

[achetronic]

Hello @seamusrex and thank you for the effort to talk in english. I would love to talk you in your native language but not able at this moment 🙂

I saw your PR and I will review it, but the point is that supporting both cases (snake_case and camelCase) at the same time is a problem because it will break not the documentation but the rest of the system. Let me explain

Right now, two APIs are available: ADK and A2A. The rest of the Magec system is crafted on top of the first one. Even the clients like Telegram one are decoupled: they are clients on top of that API.

Models in golang usually use struct tags to define the fields to decode from YAML, and those tags are defined in camelCase not in Magec, but in the source Google package, so this is not something we can change without causing future maintenance overhead:

https://github.com/google/adk-go/blob/main/server/adkrest/internal/models/runtime.go#L23-L35

Don't get me wrong, I will review your middleware and if it can do the trick without causing that overhead, I will check the code and merge it. But I wanted you to know why they are defined using camelCase 🙂

[achetronic]

@miclocher Hey, I forgot to answer you, so sorry for that!

A quick guide to use the API, which is ADK rest API under the hood. After reading it, I totally recommend you to use protocol A2A to talk to your agents. You only have to enable this option in Admin UI, in the agents you want and they will expose A2A endpoints. I recommend this because it is the future-proof option in the industry.

Anyways, the quick guide you asked:

Before you start

You need:

• A client token (mgc_...) — create one in the Admin UI → Clients
• The agent ID (a UUID) you want to talk to — visible in the Admin UI under Agents

If you haven't created any clients yet, auth is disabled and you can skip the Authorization header entirely.

List available agents

curl -s http://localhost:8080/api/v1/agent/list-apps \
  -H "Authorization: Bearer mgc_your_token"

Returns an array of agent/flow IDs:

["550e8400-e29b-41d4-a716-446655440000", "7c9e6679-7425-40de-944b-e07fc1f90ae7"]

Create a session

Sessions hold conversation state. You need one before sending messages.

curl -s -X POST \
  "http://localhost:8080/api/v1/agent/apps/YOUR_AGENT_ID/users/user1/sessions" \
  -H "Authorization: Bearer mgc_your_token" \
  -H "Content-Type: application/json" \
  -d '{}'

• Replace YOUR_AGENT_ID with the UUID from the previous step.
• user1 can be any string you want to identify the user.
• The body can be empty or {}.
• Want to pick your own session ID? Add it to the path: .../sessions/my-custom-id

Response:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "appName": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user1",
  "lastUpdateTime": 1749484800,
  "events": [],
  "state": {}
}

Grab the id — you'll need it for every message.

Send a message

curl -s -X POST http://localhost:8080/api/v1/agent/run \
  -H "Authorization: Bearer mgc_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "YOUR_AGENT_ID",
    "userId": "user1",
    "sessionId": "YOUR_SESSION_ID",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "Hey, what can you do?"}]
    }
  }'

Response — an array of events:

[
  {
    "author": "550e8400-e29b-41d4-a716-446655440000",
    "content": {
      "role": "model",
      "parts": [{"text": "Hi! I can help you with..."}]
    },
    "turnComplete": true
  }
]

Send a message with streaming (SSE)

If you want tokens as they're generated:

curl -N -X POST http://localhost:8080/api/v1/agent/run_sse \
  -H "Authorization: Bearer mgc_your_token" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "appName": "YOUR_AGENT_ID",
    "userId": "user1",
    "sessionId": "YOUR_SESSION_ID",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "Explain Kubernetes to me"}]
    },
    "streaming": true
  }'

The -N flag disables curl's output buffering so you see events in real time.

Response — a stream of SSE events:

data: {"author":"...","content":{"role":"model","parts":[{"text":"Kubernetes is"}]},"partial":true,"turnComplete":false}

data: {"author":"...","content":{"role":"model","parts":[{"text":" a container orchestrator..."}]},"partial":true,"turnComplete":false}

data: {"author":"...","content":{"role":"model","parts":[{"text":""}]},"turnComplete":true}

Keep the conversation going

Just send another message with the same sessionId. The agent remembers everything from the session:

curl -s -X POST http://localhost:8080/api/v1/agent/run \
  -H "Authorization: Bearer mgc_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "YOUR_AGENT_ID",
    "userId": "user1",
    "sessionId": "YOUR_SESSION_ID",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "How is that different from Docker?"}]
    }
  }'

Quick reference

Field	Type	What it is
appName	string	Agent or flow UUID
userId	string	Whatever you want to identify the user
sessionId	string	Session ID from the create step
newMessage.role	string	Always "user"
newMessage.parts	array	Message content — [{"text": "..."}]
streaming	bool	Set to true on /run_sse for partial tokens

Good to know

• The session must exist before you call /run or /run_sse — it won't be created automatically.
• All field names are camelCase (appName, userId, sessionId). This comes from Google's ADK library, not Magec.
• If you're sending files (images, PDFs), add them as additional parts with inlineData alongside the text part.

[seamusrex]

你好

你好@seamusrex感謝您努力用英語溝通。我很想用您的母語和您交談，但目前還不行🙂

我已看過你的 PR，我會審核它，但關鍵在於同時支援兩種命名方式（蛇形命名法和駝峰命名法）是個問題，因為它不僅會破壞文檔，還會影響系統的其他部分。讓我解釋一下。

目前，Magec 提供兩個 API：ADK 和 A2A。 Magec 系統的其餘部分都基於 ADK 建置。即使是像 Telegram 這樣的客戶端也是解耦的：它們只是基於 ADK API 的客戶端。

golang 中的模型通常使用結構體標籤來定義要從 YAML 解碼的字段，而這些標籤是在 Google 來源套件中而不是在 Magec 中以駝峰命名法定義的，因此，如果不造成未來的維護開銷，我們無法更改這一點：

https://github.com/google/adk-go/blob/main/server/adkrest/internal/models/runtime.go#L23-L35

別誤會，我會審查你的中間件，如果它能在不增加額外開銷的情況下解決問題，我會檢查程式碼並合併。但我只是想讓你知道為什麼它們要用駝峰命名法定義🙂

謝謝你 經過你的解釋 我了解你們的開發模式 往後如果有我能夠幫上忙的地方 我將會會依照你們的開發模式 這份PR如果可能破壞文檔的前提之下 請您先別使用他 這份PR我是跑過E2E與CI 但可能沒注意到會破壞文檔 造成您的不便 深感抱歉

[achetronic]

@seamusrex Could you test v0.17.0? It goes with your idea implemented but taking into account all the nested fields 🙂

[seamusrex]

@seamusrex能否測試一下 v0.17.0 版本？它實現了你的想法，並考慮到了所有嵌套字段 🙂

好的 我晚點來測試看看