1~
2To Claude Agent SDK sas dinei programmatiki prosvasi ston idio vrogcho agent pou trofodotei to Claude Code. Oi agents sas mporoun na diavazoun archeia, na ektheloun entoles shell, na psachnoun sto diadiktyo, na epexergazontai kodika, na kaloun eksoterika API mesw MCP servers kai na orchestroun sub-agents  -  ola apo liges grammes TypeScript i Python.
3~
4Se antithesi me to standard Anthropic Client SDK opou chtizetai ton diko sas tool loop, to Agent SDK diacheirizatai tin ekthelesi ergaleion, ti diacheirisi context, ta retries kai to orchestration essoteriko. Perigrafete ti thelete, parechete ta ergaleia kai o agent vriskei ton tropo.
5~
6## Architektoniki
7~
8To SDK akolouthei enan aplo vrogcho: **syllexi context, anadrome drasis, epivevaiosi, epanalipsi**.
9~
10```mermaid
11graph TD
12    Input[User Prompt] --> Loop[Agent Loop]
13    Loop --> Reason[Claude Reasons]
14    Reason --> Tool[Call Tool]
15    Tool --> Result[Tool Result]
16    Result --> Loop
17    Reason --> Done[Final Response]
18~
19    subgraph "Built-in Tools"
20        T1[Read / Write / Edit]
21        T2[Bash / Terminal]
22        T3[Glob / Grep]
23        T4[WebSearch / WebFetch]
24    end
25~
26    subgraph "Custom Tools via MCP"
27        M1[Your API]
28        M2[Database]
29        M3[Slack / GitHub / etc.]
30    end
31~
32    Tool --> T1
33    Tool --> M1
34```
35~
36To kyrio simeio eisodou einai to `query()`, pou epistrefei enan asynchrono iterator pou kanei stream minimata kathos o agent ergazetai. Kathe minima sas lei ti kanei o agent: skeftetai, kalei ergaleio, lamvanei apotelesma i paradidei to teliko output.
37~
38## Xekinontas
39~
40### Enkatastasei
41~
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45~
46# Python
47pip install claude-agent-sdk
48```
49~
50Chreiazetai ena API key tis Anthropic orismeno os `ANTHROPIC_API_KEY` sto perivallon sas.
51~
52### O protos sas agent
53~
54```typescript
55import { query } from "@anthropic-ai/claude-agent-sdk";
56~
57const conversation = query({
58  prompt: "Find all TODO comments in the codebase and create a summary",
59  options: {
60    allowedTools: ["Read", "Glob", "Grep"],
61  },
62});
63~
64for await (const message of conversation) {
65  if (message.type === "assistant") {
66    process.stdout.write(message.content);
67  }
68  if (message.type === "result" && message.subtype === "success") {
69    console.log("\nDone:", message.result);
70  }
71}
72```
73~
74Afto einai olo. O agent tha chrisimopoiisei to Glob gia na vrei archeia, to Grep gia na psaxei gia TODO patterns, to Read gia na exetasei ta apotelesmata kai tha epistrepsei mia domimeni perilipsi. Den grafete ti logiki orchestration  -  to SDK to diacheirizatai.
75~
76### Antistiocho se Python
77~
78```python
79from claude_agent_sdk import query
80~
81async for message in query(
82    prompt="Find all TODO comments in the codebase and create a summary",
83    options={"allowed_tools": ["Read", "Glob", "Grep"]},
84):
85    if message.type == "assistant":
86        print(message.content, end="")
87    if message.type == "result" and message.subtype == "success":
88        print(f"\nDone: {message.result}")
89```
90~
91## Ensomatomona ergaleia
92~
93To SDK perilamvanei ta idia ergaleia pou einai diathesima sto Claude Code:
94~
95| Ergaleio | Perigrafi |
96|------|-------------|
97| **Read** | Diavazei to periechomeno archeion |
98| **Write** | Dimiourgia neon archeion |
99| **Edit** | Stochevmenes allages se yparcha archeia |
100| **Bash** | Ekthelesi entolon shell |
101| **Glob** | Evresi archeion me vasi protypo |
102| **Grep** | Anazitisi periechomenou archeion me regex |
103| **WebSearch** | Anazitisi sto diadiktyo |
104| **WebFetch** | Lipsi URL kai epistrofi tou periechomenou tou |
105| **AskUserQuestion** | Aitisi eisodou apo ton christi |
106~
107Elegchete poia ergaleia mporei na chrisimopoiisei o agent mesw `allowedTools`. An ena ergaleio den einai sti lista, o agent den mporei na to kalesei.
108~
109## Modes adeiodotisis
110~
111Epidei oi agents ektheloun pragmatikes entoles se pragmatika systimata, oi adeies echoun simasia.
112~
113| Mode | Symperifora | Chrisi |
114|------|----------|----------|
115| `default` | Prosormosmeno `canUseTool` callback apofasizei ana klisi | Lepti elegchos |
116| `acceptEdits` | Aftomati egkrisi leitourgion archeion, erotisi gia Bash | Workflow anaptyxis |
117| `dontAsk` | Aporripsi otidhipote den einai sta allowedTools | Periorismenoi agents |
118| `bypassPermissions` | Aftomati egkrisi olou | Empistefmena sandbox perivallonta |
119| `auto` | O classifier tou montelou apofasizei gia tin asfaleia | Isorropimeni aftomaropoiisi |
120~
121```typescript
122const conversation = query({
123  prompt: "Refactor the auth module to use JWT",
124  options: {
125    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
126    permissionMode: "acceptEdits",
127  },
128});
129```
130~
131Gia chrisi se paragogi, panta trechete tous agents se sandbox perivallonta (containers, VMs) kai chrisimopoiiste ton pio periorismeno mode adeiodotisis pou epitrepei ston agent na kanei ti douleia tou.
132~
133## Dimiourgia prosarmosmeon ergaleion me MCP
134~
135I pragmatiki dynami tou SDK provlepetai apo tin epektasi ton agents me ta dika sas ergaleia. Ta prosormosmena ergaleia orizontai os in-process MCP servers  -  choris diacheirisi subprocess, choris diktyako overhead.
136~
137### Paradigm: Ergaleio kairou
138~
139```typescript
140import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
141import { z } from "zod";
142~
143const getTemperature = tool(
144  "get_temperature",
145  "Get the current temperature at a location",
146  {
147    latitude: z.number().describe("Latitude"),
148    longitude: z.number().describe("Longitude"),
149  },
150  async ({ latitude, longitude }) => {
151    const res = await fetch(
152      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
153    );
154    const data = await res.json();
155    return {
156      content: [
157        {
158          type: "text",
159          text: `Current temperature: ${data.current.temperature_2m}C`,
160        },
161      ],
162    };
163  }
164);
165~
166const weatherServer = createSdkMcpServer({
167  name: "weather",
168  version: "1.0.0",
169  tools: [getTemperature],
170});
171~
172for await (const message of query({
173  prompt: "What's the weather like in Rome?",
174  options: {
175    mcpServers: { weather: weatherServer },
176    allowedTools: ["mcp__weather__get_temperature"],
177  },
178})) {
179  if (message.type === "result" && message.subtype === "success") {
180    console.log(message.result);
181  }
182}
183```
184~
185Ta prosormosmena ergaleia akolouthoun tin convention onomasias `mcp__{onoma_server}__{onoma_ergaleiou}`. Mporeite na chrisimopoiisete wildcards sta `allowedTools`: to `"mcp__weather__*"` epitrepei ola ta ergaleia apo ton weather server.
186~
187### Paradigm: Ergaleio erotimaton vaseon dedomenon
188~
189```typescript
190const queryDb = tool(
191  "query_database",
192  "Run a read-only SQL query against the application database",
193  {
194    sql: z.string().describe("SQL SELECT query to execute"),
195  },
196  async ({ sql }) => {
197    // Validate: only allow SELECT queries
198    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
199      return {
200        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
201      };
202    }
203~
204    const result = await pool.query(sql);
205    return {
206      content: [
207        {
208          type: "text",
209          text: JSON.stringify(result.rows, null, 2),
210        },
211      ],
212    };
213  }
214);
215```
216~
217## Syndesi eksoterikou MCP servers
218~
219Pera apo ta in-process ergaleia, mporeite na syndethite me opoiodipote yparchi MCP server  -  tous idious servers pou doulevoun me to Claude Desktop, to Cursor kai allous MCP clients.
220~
221```typescript
222for await (const message of query({
223  prompt: "Check the latest issues in the frontend repo and summarize them",
224  options: {
225    mcpServers: {
226      github: {
227        command: "npx",
228        args: ["-y", "@modelcontextprotocol/server-github"],
229        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
230      },
231    },
232    allowedTools: ["mcp__github__*"],
233  },
234})) {
235  // ...
236}
237```
238~
239Mporeite na syndiasete pollaplous MCP servers. O agent vlepei ola ta ergaleia apo olous tous syndedemenous servers kai ta chrisimopoiei opos chreiazetai.
240~
241```mermaid
242graph LR
243    Agent[Your Agent] --> SDK[Agent SDK]
244    SDK --> InProcess[In-process MCP\nCustom Tools]
245    SDK --> GitHub[GitHub MCP Server]
246    SDK --> Postgres[PostgreSQL MCP Server]
247    SDK --> Slack[Slack MCP Server]
248```
249~
250## Orchestration pollalon agents
251~
252Gia polyploka workflows, mporeite na orisete exeidikevmenous sub-agents stous opoious o gonikos agent anathei ergasies. Kathe sub-agent echei to diko tou prompt, ergaleia kai area estiasis.
253~
254```typescript
255for await (const message of query({
256  prompt: "Review the PR, check for security issues, and update the changelog",
257  options: {
258    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
259    agents: [
260      {
261        name: "security-reviewer",
262        description: "Reviews code for security vulnerabilities",
263        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
264        allowedTools: ["Read", "Glob", "Grep"],
265      },
266      {
267        name: "changelog-writer",
268        description: "Updates the CHANGELOG.md file based on recent changes",
269        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
270        allowedTools: ["Read", "Edit", "Bash"],
271      },
272    ],
273  },
274})) {
275  // The parent agent will:
276  // 1. Read the PR diff
277  // 2. Delegate security review to security-reviewer
278  // 3. Delegate changelog update to changelog-writer
279  // 4. Synthesize results
280}
281```
282~
283Prostheste to `"Agent"` sta `allowedTools` tou gonikou agent gia na energopoiisete tin anathesi. Oi sub-agents trechoun me ta dika tous ergaleia kai den echoun prosvasi sta ergaleia tou gonea ektos an afto epitrapei rita.
284~
285```mermaid
286graph TD
287    Parent[Parent Agent] --> SR[Security Reviewer\nRead, Glob, Grep]
288    Parent --> CW[Changelog Writer\nRead, Edit, Bash]
289    SR --> Report[Security Report]
290    CW --> Updated[Updated CHANGELOG]
291    Report --> Parent
292    Updated --> Parent
293    Parent --> Final[Final Summary]
294```
295~
296## Sessions kai synecheia
297~
298Oi agents mporoun na diatiroun context metaxy pollalon queries chrisimopoiontas sessions. Katagrapsite to `session_id` apo tin proti allilepidrasi kai perasete to sto `resume` gia epomenes erotiseis.
299~
300```typescript
301let sessionId: string | undefined;
302~
303// First query
304for await (const message of query({
305  prompt: "Read the project structure and understand the architecture",
306  options: { allowedTools: ["Read", "Glob", "Grep"] },
307})) {
308  if (message.type === "init") {
309    sessionId = message.session_id;
310  }
311}
312~
313// Follow-up query (same session, full context preserved)
314for await (const message of query({
315  prompt: "Now refactor the auth module based on what you learned",
316  resume: sessionId,
317  options: { allowedTools: ["Read", "Edit", "Bash"] },
318})) {
319  // Agent remembers the full project context from the first query
320}
321```
322~
323## Claude Managed Agents
324~
325An den thelete na filoxenisete tin ypodomi tou agent monoi sas, to **Claude Managed Agents** (pou xekinise ton Aprilio 2026) parechei mia pliros diacherismeni yperisia cloud. I Anthropic trechei ta containers, diacheirizatai to scaling kai parechei streaming API.
326~
327```mermaid
328graph LR
329    subgraph "Self-hosted (Agent SDK)"
330        Code[Your Code] --> SDK2[Agent SDK]
331        SDK2 --> API[Claude API]
332        SDK2 --> Tools[Your Tools]
333    end
334~
335    subgraph "Managed Agents"
336        App[Your App] --> MAPI[Managed Agents API]
337        MAPI --> Container[Anthropic-hosted Container]
338        Container --> API2[Claude API]
339        Container --> Tools2[Tools in Container]
340    end
341```
342~
343I vasiki diafora: me to Agent SDK, trechete ton vrogcho agent stin diki sas ypodomi. Me ta Managed Agents, i Anthropic filoxeni kai trechei ton agent gia esenas. Epikinonite mesw enos API vasimenon se sessions kai lamvanete gegonota mesw Server-Sent Events.
344~
345**Timologisi:**
346- **Agent SDK**: mono oi standard times token tou Claude API. Eseis diacheirizeste to hosting.
347- **Managed Agents**: times token syn 0,08 USD ana ora session (chreosi ana millisecond).
348~
349## Best practices gia paragogi
350~
351### 1. Panta apomononete
352~
353Pote min trechete agents me aperioristos adeies se michani paragogis. Chrisimopoiiste containers (Docker, Fly.io, Modal) i sandbox perivallonta (E2B, Vercel Sandbox).
354~
355### 2. Periorismos prosvasis ergaleion
356~
357Akolouthiste tin archi tis elachistis adeiodotisis. Enas agent pou dimiourgi anafores den chreiazetai `Bash` i `Write`.
358~
359```typescript
360// Too permissive
361allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
362~
363// Better: only what's needed
364allowedTools: ["Read", "Glob", "Grep"]
365```
366~
367### 3. Chrisimopoiiste hooks os asfalistikes diktyes
368~
369Ta hooks sas epitrepoun na parakolouthite kliseis ergaleion prin kai meta tin ekthelesi. Chrisimopoiiste ta gia logging, validation kai rate limiting.
370~
371```typescript
372const conversation = query({
373  prompt: "Analyze the codebase",
374  options: {
375    allowedTools: ["Read", "Glob", "Grep"],
376    hooks: {
377      PreToolUse: async (toolName, input) => {
378        console.log(`Tool call: ${toolName}`, input);
379        // Return false to block the call
380        if (toolName === "Bash" && input.command.includes("rm")) {
381          return false;
382        }
383        return true;
384      },
385    },
386  },
387});
388```
389~
390### 4. Diacheiristite ta sfalata me charin
391~
392O vrogchos tou agent mporei na paraxei sfalata  -  apotyechies ergaleion, oria API, ypervasi tou context window. Panta elegchete tous typous minimaton.
393~
394```typescript
395for await (const message of conversation) {
396  switch (message.type) {
397    case "assistant":
398      // Agent reasoning
399      break;
400    case "tool_use":
401      // Agent is calling a tool
402      break;
403    case "result":
404      if (message.subtype === "error") {
405        console.error("Agent failed:", message.error);
406      }
407      break;
408  }
409}
410```
411~
412### 5. Parakolouthiste ti chrisi token
413~
414Oi vrogchoi ton agents mporoun na katanalwsoun simantika tokens, eidika me megales vaseis kodika. To SDK perilamvanei aftomati sympiesi context, alla tha prepei na parakolouthite ti chrisi.
415~
416## Symperasma
417~
418To Claude Agent SDK metatrepei ena LLM apo michani apantiseon se kati pou prosmoiazei se junior developer. Oi agents sas mporoun na diavazoun, na grafoun, na ektheloun, na epivevainoun kai na epanalmavanoun  -  to idio workflow pou akolouthei enas anthropos.
419~
420Xekiniste mikra: chtisteai enan agent me merika ensomatomona ergaleia. Meta prostheste prosormosmena MCP ergaleia gia ton diko sas tomea. Klimakosete se orchestration pollalon agents otan ta workflows sas apaitoun exeidikevsi.
421~
422O vrogchos tou agent einai o idios pou trofodotei to Claude Code. An mporei na chtisi logismiko, oi agents sas mporoun kai aftoi.
423~
424> **Lista elegchou gia xekinima:**
425>
426> - [x] Egkatastiste to SDK (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Oriste to `ANTHROPIC_API_KEY` sto perivallon sas
428> - [x] Chtisteai enan aplo agent me ensomatomona ergaleia (Read, Glob, Grep)
429> - [x] Prostheste ena prosormosmeno ergaleio mesw in-process MCP server
430> - [x] Syndeste enan eksoteriko MCP server (GitHub, PostgreSQL, klp.)
431> - [x] Ylopoiiste orchestration pollalon agents me sub-agents
432> - [x] Rythiste ena sandbox perivallon gia paragogi
433> - [x] Prostheste hooks gia logging kai asfalistikes diktyes
434~