developing-agents

name	developing-agents
description	Use when implementing or debugging agents, tool-calling assistants, or multi-step AI runtimes and you need correct message conversion, tool-call handling, replayed history, loop continuation, or provider/API compatibility across SDKs, proxies, or direct upstream model APIs.
license	CC-BY-NC-4.0

Developing Agents

Overview

Use this skill when the hard part is no longer “call a model once”, but “make the runtime behave correctly across multiple steps”.

Focus on implementation, not product design. The main failure modes are almost always:

• wrong message schema at one boundary
• tool call parses correctly but tool result is replayed incorrectly
• first turn works but second turn fails
• streaming and non-streaming behave differently
• provider/proxy compatibility is only partial

When to Use

• You are implementing tool calling, agent loops, chat replay, memory replay, or resumed sessions
• A model can call tools, but the assistant does not continue correctly after tool execution
• OpenAI-compatible or Anthropic-compatible payloads work for one turn but break on later turns
• An SDK, adapter, or proxy accepts the request but rejects replayed history
• Tool ids, tool names, tool inputs, or tool results are getting mixed up
• Streaming output looks correct, but the final persisted history is wrong

Do not use this skill for simple one-shot text generation with no tools and no replayed history.

API Format References

Before writing adapters, read the actual provider message format instead of guessing.

OpenAI-style APIs

• Typical shape: chat-completions/messages or responses-style structured input
• Common concepts: messages, assistant tool_calls, tool messages with tool_call_id, streaming deltas, finish reasons
• Docs:
  • https://platform.openai.com/docs/api-reference/chat
  • https://platform.openai.com/docs/guides/function-calling

Anthropic-style APIs

• Typical shape: messages array with structured content blocks
• Common concepts: tool_use, tool_result, block-based content instead of plain assistant/tool strings
• Docs:
  • https://docs.anthropic.com/en/api/messages
  • https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview

Practical rule

“OpenAI-compatible” and “Anthropic-compatible” usually mean partially compatible until proven otherwise. Verify the exact fields you depend on:

• assistant tool-call shape
• tool result shape
• streaming shape
• finish reasons
• replay/resume behavior

Core Invariants

Keep these separate at all times:

• tool id: synthetic runtime/provider identifier
• tool name: real executable capability
• tool input: structured invocation payload
• tool output: result returned after execution

If any of these collapse into one field, replay turns will eventually break.

Also preserve this invariant:

A tool result is not just something to display. It is input to the next model step.

Implementation Rules

1. Normalize messages at the boundary

Do not pass user-facing message shapes directly into the SDK unless the SDK explicitly accepts them.

You usually need explicit conversion for:

• assistant tool calls
• tool result messages
• content arrays vs plain strings
• provider-specific content blocks

Good:

• client/API messages → runtime/SDK messages
• runtime/SDK messages → upstream/provider messages

Bad:

• letting half-normalized objects leak through multiple layers
• assuming OpenAI-style history is already valid SDK history
• assuming SDK-native messages are already valid upstream payloads

2. Treat first turn and replay turn as different test targets

A tool integration is not correct when the model requests a tool once.

It is correct when this full path works:

1. model requests tool
2. runtime executes tool
3. runtime records tool result
4. tool call + tool result are replayed into the next step
5. assistant continues correctly

3. Keep a canonical tool registry

Your runtime should have one authoritative source for:

• tool name
• input schema
• execution function
• permission/approval policy if any

Everything else should map back to that registry.

4. Preserve message meaning across every conversion

If your system has more than one boundary, verify all of these conversions explicitly:

• client request → runtime message
• runtime message → SDK message
• SDK message → upstream payload
• upstream response → SDK/runtime output
• runtime output → client-visible response

Fixing one direction does not fix the others.

5. Streaming must preserve the same semantics as non-streaming

Streaming and non-streaming should agree on:

• tool name
• tool id
• tool input
• finish reason
• replayable history after completion

If the streamed path emits logically different events than the non-streamed path, you have two incompatible runtimes.

Tool-Call Loop Pattern

The minimal correct loop is:

1. Normalize incoming history into runtime/SDK messages
2. Call the model
3. If there are no tool calls, return assistant output
4. If there are tool calls:
   • validate tool names against the canonical registry
   • execute the tools
   • append tool results in the runtime’s canonical message format
   • call the model again with replayed history
5. Repeat until a real stop condition is reached

Good stop conditions:

• assistant returns normal content with no tool calls
• configured max-step limit reached
• approval required but not granted
• unrecoverable invalid tool call

Bad stop conditions:

• “a tool ran, so we’re done”
• “the provider returned something parseable”
• “the first chunk looked fine”

Replay and History Rules

Replay bugs are the most common real-world agent bugs.

Always distinguish:

• client-visible history
• runtime history
• provider/upstream history

These are often related, but they are not always identical.

For replayed turns, verify all of these:

• prior assistant tool call still exists
• tool result still points to the correct tool call id
• real tool name is preserved
• tool result is encoded in the schema expected by the next boundary
• the next model step is actually triggered

Message Conversion Advice

OpenAI-style history

Typical conversions you may need:

• assistant tool_calls → SDK tool-call parts
• tool messages with tool_call_id → SDK tool-result parts
• content arrays → text parts or strings depending on the boundary

Anthropic-style history

Typical conversions you may need:

• tool_use blocks → runtime tool-call records
• tool_result blocks → runtime tool-result records
• block arrays → client-facing messages or provider-specific replay payloads

Practical rule

Never convert by field name alone. Convert by meaning:

• what is assistant text?
• what is a tool request?
• what is a tool result?
• what must be replayed next turn?

Debugging Workflow

When tool calling or continuation breaks, inspect these in order:

1. raw client request/history
2. normalized runtime/SDK messages
3. actual upstream payload
4. actual upstream response
5. parsed runtime response
6. replayed follow-up payload
7. final user-visible output

At each step, ask:

• Is the tool name still the real executable name?
• Is the tool id still matched correctly?
• Is the tool input still valid for this boundary?
• Is the tool output still valid for this boundary?
• Should the loop continue from here?

Do not jump directly from final symptom to upstream blame.

Verification Matrix

Before claiming the integration works, verify all of these:

Case	Must pass
Plain text, no tools	Assistant returns normal output
First-turn tool call	Correct tool name, id, and input
Tool result replay	Assistant continues correctly on next turn
Resumed/persisted history	Replayed tool call + result still work
Streaming tool path	Same semantics as non-streaming
Tool error path	Correct error propagation and loop behavior
Multi-tool environment	No synthetic id/name confusion

If you only verified first-turn tool calling, you did not verify the agent.

Quick Reference

If the symptom is:

• tool called, no continuation → inspect replayed tool result message shape
• unavailable synthetic tool name → inspect tool id vs tool name mapping
• first turn works, second turn fails → inspect replay normalization
• stream works, saved history breaks → compare streamed events vs persisted messages
• provider says invalid prompt → inspect SDK-facing message schema, not just client payload

Common pitfalls from real debugging:

• SDK accepts first turn but rejects resumed history → you probably normalized user text but not assistant tool_calls and tool result messages into SDK-native message parts
• Tool execution succeeds but final answer is empty → the loop often stopped because the tool result was displayed but not replayed as input to the next model step
• Synthetic ids like toolu_* leak into the tool name field → keep toolCallId and toolName separate; recover the real tool name from the registry or schema match, not from display output
• Replay turn breaks only in multi-tool environments → single-tool heuristics hide bugs; verify name recovery when several tools are advertised
• Targeted tests hang or mislead → use direct runtime probes when the test runner itself is ambiguous, but still keep a regression test for the confirmed bug

Common Mistakes

• Treating agent bugs as “model bugs” before checking message conversion
• Testing only first-turn tool requests
• Reconstructing tool names from ids when a canonical registry already exists
• Replaying tool results as display strings when the next boundary expects structured parts
• Assuming OpenAI-compatible or Anthropic-compatible means fully compatible
• Writing “agent development” guidance that focuses on architecture slogans instead of concrete runtime behavior

Minimal Acceptance Criteria

Do not consider the implementation correct unless all of these are true:

• first-turn tool calls work
• second-turn after tool result works
• at least one replay/resume case works
• streaming and non-streaming agree on semantics
• tool ids and tool names remain distinct throughout the system
• there is a single canonical tool registry